# AGENTS.md

Read this before changing anything in this repository.

## Project Identity
- Package name: `omnictl` (PyPI).
- Primary import namespace: `omni`.
- Compatibility alias: `omnisdk` (not `omni_sdk`).
- CLI command: `omnipy`.
- Repository: `https://github.com/SparkAIUR/omni-sdk`.

## Core Product Decisions (Do Not Drift)
- Async-first transport (`httpx`) with retries + conservative caching.
- Unified sync/async client DX in `OmniClient`:
  - sync methods: normal name
  - async methods: same method prefixed with `a`
- Config precedence:
  1. runtime dict/model
  2. explicit `config_path`
  3. `OMNI_SDK_CONFIG`
  4. default path search
- Persistent state backend: SQLite by default.
- Upstream-aligned versioning: match Omni `X.Y.Z`; SDK-only patches use `.postN`.
- CLI parity target: mirror `omnictl` behavior where implemented.

## Repo Layout (High Signal)
- `src/omni/client/`: async client + unified client + singleton helpers.
- `src/omni/cli/main.py`: Typer CLI command tree.
- `src/omni/cli/talos_manager.py`: managed talosconfig persistence logic.
- `src/omni/state/store.py`: sqlite schema for preferences/cache/history.
- `src/omni/api/`: API facades + CRD resolver (`crd.py`).
- `src/omni/generated/`: generated artifacts (`methods.py`, `models.py`, `crd_catalog.py`).
- `scripts/`: generators + upstream drift updater.
- `docs/`: MDX docs used for docs site.
- `refs/libs/omni` and `refs/libs/sidero-docs`: upstream source references only.

## Required Tooling
- Use `uv` for all Python workflows.
- Common commands:
  - `uv sync --extra dev`
  - `uv run ruff check .`
  - `uv run mypy src`
  - `uv run pytest`
  - `uv run python scripts/update_upstream.py`

## Generated Artifact Rules
- If changing upstream-derived behavior, regenerate artifacts.
- Generated files are source of truth for runtime:
  - `src/omni/generated/methods.py`
  - `src/omni/generated/models.py`
  - `src/omni/generated/crd_catalog.py`
- `upstream.lock` must stay in sync with updater outputs.

## Talos Wrapper Notes
- `omnipy talos` / `omnipy t` proxies to `talosctl`.
- Wrapper injects missing `--talosconfig` and `--context` from managed state.
- Managed contexts use: `omni/<instance>/<cluster-or-generic>`.
- First `talos` call may need `--nodes`; wrapper persists later defaults once provided.

## History + Autocomplete
- `command_history` table stores redacted commands, capped at 2000 entries.
- Never store secrets in plain text; redaction behavior is security-sensitive.
- Completion sources prioritize CRD catalog and history suggestions.

## Testing Expectations
- For any CLI change, add/update tests in `tests/test_cli.py`.
- For state/history changes, update `tests/test_state_history.py` and redaction tests.
- For CRD behavior, update `tests/test_crd_resolver.py`.
- Local acceptance before merge:
  - lint, typecheck, full tests.

## Documentation Expectations
- Keep README and `docs/*.mdx` aligned with implemented behavior.
- Prefer task-based examples for both CLI and SDK.
- Use `refs/libs/sidero-docs` as workflow reference when expanding Omni usage docs.

## Safety and Collaboration
- Do not revert unrelated user changes.
- Avoid destructive git commands.
- Keep commits small and scoped.
- If behavior diverges from locked product decisions, call it out explicitly before implementing.
