Metadata-Version: 2.3
Name: augint-opencodex
Version: 0.9.0
Summary: Manage local Codex and OpenCode repo config from .ai-opencodex.json
Author: Augmenting Integrations
Requires-Dist: click>=8.1.0
Requires-Dist: pydantic>=2.11.0
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# augint-opencodex

`augint-opencodex` manages local Codex and OpenCode repository configuration from a
single tracked manifest, `.ai-opencodex.json`.

The current tool ships a real CLI with:

- `ai-opencodex init` to create `.ai-opencodex.json` when needed and create any
  missing managed files without overwriting existing ones
- `ai-opencodex update` to merge rendered config into managed files, refresh
  generated docs and skills, and remove stale managed files
- `ai-opencodex doctor` to inspect manifest resolution, generated files, local
  ignore setup, and staged generated artifacts
- a first-pass profile model with `augint` and `gov`
- local-only ignore handling through `.git/info/exclude`

`ai-opencodex` is the preferred executable name. The published package still keeps
`ai-codex` as a compatibility alias.
The old `sync` workflow is now split into `init` and `update`.

## Installation

For local development:

```bash
uv sync --group dev
```

Once the package is published, the intended install flows are:

```bash
uvx --from augint-opencodex ai-opencodex init
uv tool install augint-opencodex
ai-opencodex init
```

## Manifest

This tool expects a tracked `.ai-opencodex.json` file in the target repository.

- `ai-opencodex init` creates the manifest from a bundled template when it is
  missing.
- `ai-opencodex init` never overwrites an existing manifest; it warns and skips it.
- `ai-opencodex update` requires the manifest to already exist.

A generated starter manifest looks like this:

```json
{
  "$schema": "https://svange.github.io/augint-opencodex/ai-opencodex.schema.json",
  "version": 1,
  "profile": "augint",
  "references": [],
  "blocked_paths": [],
  "content_policy": {
    "no_emojis": true,
    "no_ai_mentions": true
  },
  "shell_guardrails": {
    "ask": [],
    "deny": []
  },
  "patterns": {
    "org_python_library": false
  },
  "opencode": {
    "enabled": true,
    "default_model": null,
    "local_provider": {
      "kind": "openai-compatible",
      "name": "ollama",
      "base_url": "http://host.docker.internal:11434/v1"
    },
    "models": [],
    "bedrock": {
      "enabled": false,
      "models": []
    }
  },
  "codex": {
    "provider": "openai",
    "model": null,
    "approval_policy": null,
    "sandbox_mode": null,
    "web_search": null
  }
}
```

The primary schema lives in
[`schemas/ai-opencodex.schema.json`](schemas/ai-opencodex.schema.json).

### OpenCode and Codex manifest fields

The `opencode` and `codex` sections let the manifest fully express non-secret
local tool configuration:

- `opencode.local_provider` - OpenAI-compatible local endpoint (for example
  Ollama) rendered as `provider.<name>.options.baseURL` in `opencode.json`
- `opencode.default_model` - top-level `model` in `opencode.json`
- `opencode.models` - curated catalog attached to the local provider
- `opencode.bedrock.enabled` / `opencode.bedrock.models` - toggles the
  `amazon-bedrock` provider entry with the listed model IDs
- `codex.provider` - `openai` or `aws`; emitted as a runtime hint in
  `.codex/config.toml`
- `codex.model`, `codex.approval_policy`, `codex.sandbox_mode`,
  `codex.web_search` - override the defaults carried by the active profile

## Commands

Initialize a repository:

```bash
uv run ai-opencodex init
```

Preview initialization without writing:

```bash
uv run ai-opencodex init --dry-run
```

Update managed files from the manifest:

```bash
uv run ai-opencodex update
```

Preview pending updates without writing:

```bash
uv run ai-opencodex update --dry-run
```

Fail if managed files are out of date:

```bash
uv run ai-opencodex update --check
```

Inspect the current repository state:

```bash
uv run ai-opencodex doctor
```

## Update semantics

`init` is create-only:

- creates `.ai-opencodex.json` if it is missing
- creates any missing managed files
- skips existing files with a warning instead of overwriting them

`update` is merge-oriented:

- reads `.ai-opencodex.json`
- merges structured config files such as `opencode.json` and
  `.codex/config.toml`
- refreshes generated markdown and skill files from bundled templates
- lets new managed values win conflicts
- removes stale managed files that are no longer expected

## Templates and generated skills

Bundled template assets now live under `src/augint_opencodex/templates/` instead
of being embedded inline in renderer code.

That includes:

- the manifest starter template
- generated `.codex/config.toml` and `.ai-opencodex.md` templates
- the generated `opencode.json` template shell
- the shared skills README template
- the org Python tooling skill file, including valid YAML frontmatter

## Generated files

The current tool manages:

- `.ai-opencodex.md`
- `.codex/config.toml`
- `opencode.json`
- `.agents/skills/README.md`
- `.agents/skills/org-python-tooling/SKILL.md` when
  `patterns.org_python_library` is enabled

Managed outputs are added to `.git/info/exclude` by default so target
repositories do not need to commit them.

## Canonical ownership

There is one source of truth for each managed file and one tool responsible for
runtime-only behavior.

| File                        | Owner              | Notes                                   |
| --------------------------- | ------------------ | --------------------------------------- |
| `.ai-opencodex.json`        | user (tracked)     | Source of truth for managed files       |
| `opencode.json`             | `augint-opencodex` | Repo root; managed                      |
| `.codex/config.toml`        | `augint-opencodex` | Repo root; managed                      |
| `.ai-opencodex.md`          | `augint-opencodex` | Repo root; managed                      |
| `.agents/skills/**`         | `augint-opencodex` | Managed                                 |

Managed files should not be hand-edited unless you intend those edits to be
merged or replaced on the next `ai-opencodex update`.

### Runtime ownership (augint-shell)

`augint-shell` is responsible only for runtime and container behavior:

- bind-mounting `.codex/` and `opencode.json` into the container
- injecting secrets (`OPENAI_API_KEY`, AWS credentials) at launch time
- selecting Bedrock vs OpenAI auth paths based on the manifest's
  `codex.provider` / `opencode.bedrock.enabled` signals
- CLI launch flags (`ai-shell opencode`, `ai-shell codex`)

`augint-shell` should not ship duplicate template copies of `opencode.json` or
`.codex/config.toml`, and `.ai-shell.yaml` should not duplicate the shape of
`.ai-opencodex.json`.

## Dogfooding this repo

This repository is set up to dogfood the generated instructions flow without a
root `AGENTS.md`.

1. Keep `.ai-opencodex.json` tracked in the repo root.
2. Run `uv run ai-opencodex update` to generate `.ai-opencodex.md`,
   `.codex/config.toml`, and the other local-only artifacts.
3. Start Codex with `CODEX_HOME=$(pwd)/.codex codex` so Codex uses the generated
   `.codex/config.toml` as its home config and discovers `.ai-opencodex.md` via
   `project_doc_fallback_filenames`.

Avoid creating a root `AGENTS.md` here. Codex checks `AGENTS.md` before fallback
filenames in the same directory, so a root `AGENTS.md` would shadow
`.ai-opencodex.md` and split Codex from the generated OpenCode instructions.

## Development

```bash
make install
make test
make format
make typecheck
make build
```
