Metadata-Version: 2.4
Name: corsette
Version: 0.2.1
Summary: Portable AI context product with OKF knowledge and generated adapters.
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: PyYAML>=6
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"

<p align="center">
  <img src="assets/corsette-logo.png" alt="Corsette logo" width="640">
</p>

# Corsette

Corsette is a portable AI context package. It stores reusable knowledge, agents, skills, and commands in canonical source files, then renders installable output for multiple agent runtimes such as OpenCode and pi.dev.

The project is designed for public distribution: generated files are disposable, private context stays local, and model choices are expressed through semantic profiles instead of concrete provider IDs.

## What Corsette contains

| Area | Purpose |
|---|---|
| `okf/knowledge/` | Portable Markdown knowledge vault using OKF-style frontmatter. |
| `catalog/skills/` | Canonical skill definitions and prebuilt skill packages. |
| `catalog/agents/` | Canonical agent definitions using semantic `model_profile` values. |
| `catalog/commands/` | Canonical slash-command prompts. |
| `adapters/` | Generated runtime packages for OpenCode, pi.dev, aicontext, Claude, and agents-md. |
| `tools/` | Validation, privacy scrubbing, and generation scripts. |
| `packages/corsette/` | Python CLI for local workflows and ingestion helpers. |

## Core capabilities

- **SDD + TDD:** OpenSpec-shaped behavior contracts plus Corsette's five-agent harness and mutation-testing discipline.
- **AutoResearch:** source capture, iteration, and finding synthesis into OKF notes.
- **CodeGraph:** Graphify-backed code graph artifact capture.
- **Model eval:** semantic model profile evaluation and local model resolution.

## Install for local development

```bash
python3 -m pip install -e .
```

After installation, the CLI is available as `corsette`:

```bash
corsette --help
corsette validate
corsette scrub
corsette generate --adapter opencode
corsette generate --adapter pi-dev
```

You can also run the module directly without installing:

```bash
python3 -m corsette --help
```

## Install on another machine

Clone the public repository, create an isolated Python environment, install the package, then regenerate runtime adapters from canonical sources.

```bash
git clone https://github.com/arturonaredo/corsette.git
cd corsette
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e '.[dev]'
corsette --help
```

Generate the runtime package you want to install into your agent runtime:

```bash
corsette generate --adapter opencode
corsette generate --adapter pi-dev
```

For OpenCode, copy or symlink `adapters/opencode/generated/.opencode/` into the target project or user OpenCode configuration. For pi.dev, install or copy from `adapters/pi-dev/generated/` according to your pi.dev setup.

Private overlays are intentionally not part of the public repository. Keep local machine-specific context in `.corsette/` or `okf/private/`, and keep concrete model IDs in environment variables referenced by `catalog/profiles/model-profiles.yaml`.

Run this smoke check after installing on a new machine:

```bash
corsette validate
corsette scrub
corsette generate --adapter opencode --check
corsette generate --adapter pi-dev --check
python -m pytest packages/corsette/tests
```

## Generate adapter output

Canonical files live in `okf/` and `catalog/`. Runtime-specific files are generated and should not be edited by hand.

```bash
corsette generate --adapter opencode
corsette generate --adapter pi-dev
```
Generated output is written under:

- `adapters/opencode/generated/`
- `adapters/pi-dev/generated/`

Those directories are ignored by git and can always be regenerated.

## Install generated packages

### OpenCode

Generate the OpenCode adapter, then copy or symlink the generated `.opencode/` content into the target project or user configuration according to your OpenCode setup.

```bash
corsette generate --adapter opencode
```

### agents-md

Generates a single `AGENTS.md` at the project root that follows the AGENTS.md convention used by tools like Aider and some Cursor modes. The file lists the canonical project layout, core rules, available skills, agents, commands, and the most useful CLI entry points. Sources are the same as every other adapter — `okf/`, `catalog/`, and the routing matrix.

```bash
corsette generate --adapter agents-md
```

### pi.dev

Generate the pi.dev adapter, then install from the generated package directory.

```bash
corsette generate --adapter pi-dev
# install from adapters/pi-dev/generated according to your pi.dev setup
```

The pi.dev package includes skills, prompts, agent prompt files, and an extension bridge.

## CLI workflows

Corsette includes a small Python CLI for repository maintenance and ingestion helpers.

```bash
corsette okf-youtube <url> --offline-metadata metadata.json --offline-transcript transcript.vtt
corsette okf-code-graph <path> --offline-artifacts path/to/graphify-output
corsette okf-notebooklm import notes exported-note.md
corsette okf-notebooklm import dir exported-notes/
corsette okf-research "investigate a topic" --source README.md
corsette okf-research-run "investigate a topic" --source README.md --max-iterations 3
corsette okf-sdd-tdd "installable package" --scenario "package installs locally"
# writes openspec/changes/installable-package/ plus an OKF spec note
corsette okf-capture-web saved-page.html --url https://example.test/page
corsette capture-server --host 127.0.0.1 --port 8765
# then load capabilities/chrome-capture/extension/ as an unpacked Chrome extension
corsette okf-model-eval models.json
corsette okf-model-judge models.json --goal "pick a strong general model" [--live --api-url <url> --api-key <key>]
corsette okf-model-telemetry telemetry.json
corsette okf-improve
corsette okf-index
corsette okf-catalog-index
corsette okf-catalog-index --no-mobile  # exclude the TIER 3 iOS/Android mobile pack
corsette release 0.2.0                # dry-run: runs validate, scrub, generate, pytest (no build, no version bump)
corsette release 0.2.0 --apply       # also bumps pyproject.toml and runs python -m build
corsette release 0.2.0 --apply --tag  # also creates git tag v0.2.0
corsette release 0.2.0 --apply --tag --push  # also pushes the tag to origin
corsette okf-release-checklist v0.1.0
corsette install-pack mobile --output /tmp/mobile-pack  # extract the TIER 3 iOS/Android skill pack without touching the source catalog
corsette okf-doctor  # run validate + scrub + generate --check (5 adapters) + pytest; does not mutate the checkout
corsette upgrade  # post-install umbrella: report current version, scan for deprecated CLI names, write OKF report
corsette upgrade --release-metadata release.json --apply --venv .venv  # actually install the release + rewrite files in place
corsette upgrade --target-dir ~/projects  # scan a specific directory for deprecated CLI references
corsette upgrade --target-dir ~/projects --apply  # scan + rewrite files in place
corsette okf-visual-plan "review UI" --summary "Plan the review UI" --file src/review.tsx
corsette okf-visual-recap "workflow work" --summary "Summarize implemented workflow changes" --file packages/corsette/src/corsette/workflows.py
corsette okf-daily-log --scope corsette --entry "what you did" --source opencode
# appends to okf/knowledge/daily-log-corsette-YYYY-MM-DD.md
```

The ingestion commands write OKF-compatible notes under `okf/knowledge/`.

## Verification

Run these before publishing or opening a pull request:

```bash
corsette validate
corsette scrub
corsette generate --adapter opencode --check
corsette generate --adapter pi-dev --check
corsette generate --adapter aicontext --check
corsette generate --adapter claude --check
corsette generate --adapter agents-md --check
python3 -m pytest packages/corsette/tests
python3 -m build
```

GitHub Actions runs the same validation contract on pull requests and pushes to `main`, including a wheel install smoke test.

## Public-safety rules

This repository is intended to be public. Do not commit:

- API keys, tokens, credentials, or `.env` files;
- private IP addresses or internal hostnames;
- private provider names, company-specific infrastructure, or internal model IDs;
- generated adapter output;
- local private vault content under `.corsette/` or `okf/private/`.

Use semantic model profiles such as `balanced_coding`, `deep_reasoning`, `strong_general`, and `fast_utility` in public catalog files.

## Maintenance rules

- Edit canonical sources in `okf/` and `catalog/`.
- Never hand-edit generated files under `adapters/*/generated/`.
- Record substantial research, decisions, and findings as OKF notes under `okf/knowledge/`.
- Keep repository-facing documentation in English.
- Run validation, scrub, generation checks, and tests before claiming work is complete.
