Metadata-Version: 2.4
Name: corsette
Version: 0.2.4
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

> **A governed, portable catalog of agents, skills, knowledge, commands, and MCP definitions—rendered into reproducible runtimes for AI coding tools.**

Corsette keeps reusable AI-tool configuration in version-controlled, runtime-neutral sources. It renders only the pieces you choose for [OpenCode](#supported-runtimes), Claude Code, or pi.dev, without requiring network access during setup.

## Quick start

Install the CLI with your preferred Python tool manager:

```bash
pipx install corsette
# or
uv tool install corsette
```

Run the guided installer:

```bash
corsette setup
```

For scripts, CI, or a repeatable project installation, provide every choice explicitly:

```bash
corsette setup \
  --adapter opencode \
  --scope project \
  --components agents,skills \
  --yes
```

Preview the exact filesystem changes first:

```bash
corsette setup \
  --adapter opencode \
  --scope project \
  --components agents,skills \
  --dry-run
```

## Supported runtimes

| Runtime | Adapter value | Agents | Skills | Commands | MCP definitions |
|---|---|:---:|:---:|:---:|:---:|
| [OpenCode](https://opencode.ai/) | `opencode` | ✓ | ✓ | ✓ | ✓ |
| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | `claude` | ✓ | — | ✓ | — |
| [pi.dev](https://github.com/badlogic/pi-mono) | `pi-dev` | ✓ | ✓ | ✓ | — |

Only these three adapters are maintained. Corsette no longer provides aicontext or generated `AGENTS.md` adapters.

## Selective setup

`corsette setup` is the recommended user-facing workflow. It uses standard terminal prompts—no additional TUI dependency—and supports the same choices non-interactively.

```text
corsette setup [--adapter opencode|claude|pi-dev]
               [--scope project|global]
               [--components agents,skills,commands,mcp]
               [--with-rtk] [--yes] [--dry-run]
```

### Safety guarantees

- Works from a checkout or an installed wheel; setup itself does not make network requests.
- Shows a preview and asks for confirmation unless `--yes` is passed.
- **Project installs refuse to overwrite** an already occupied selected component path.
- A global OpenCode setup renames the current `~/.config/opencode` to a timestamped `opencode.pre-corsette-backup-*` directory before installing the selected runtime.
- `--with-rtk` records that RTK guidance is requested; it does not silently download or install third-party software.

### Examples

Install all OpenCode components into the current Corsette project interactively:

```bash
corsette setup --adapter opencode --scope project
```

Install Claude agents and its generated `CLAUDE.md` into a project:

```bash
corsette setup --adapter claude --scope project --components agents --yes
```

Install only pi.dev prompts:

```bash
corsette setup --adapter pi-dev --scope project --components commands --yes
```

Install a global OpenCode runtime after reviewing its preview:

```bash
corsette setup --adapter opencode --scope global --components agents,skills,commands,mcp
```

## What is in the catalog?

| Catalog | Canonical source | Current contents |
|---|---|---:|
| Agents | [`catalog/agents/`](catalog/agents/) | 80 |
| Skills | [`catalog/skills/`](catalog/skills/) | 34 |
| Commands | [`catalog/commands/`](catalog/commands/) | 33 |
| MCP definitions | [`catalog/mcp/`](catalog/mcp/) | 17 |

The catalog is backed by reusable, privacy-reviewed [OKF knowledge](okf/knowledge/index.md). Browse the [catalog overview](catalog/README.md), [adapter documentation](adapters/README.md), and the [public catalog architecture](okf/knowledge/architecture/public-catalog.md) for the source-of-truth model.

## Advanced and scriptable workflow

`setup` composes the lower-level commands below. Use them only when you want to separate generation from installation or control install placement directly.

```bash
# Generate disposable output from canonical catalog and OKF sources.
corsette generate --adapter opencode

# Install that generated output locally.
corsette install --adapter opencode --local

# Back up and replace the full global OpenCode runtime.
corsette install --adapter opencode --global-runtime

# Remove locations recorded for a prior adapter install.
corsette install --adapter opencode --revert
```

Generated files under `adapters/*/generated/` are disposable. Do not edit them; change the canonical material under [`catalog/`](catalog/) and [`okf/`](okf/) instead.

## Validate a checkout

For contributors and catalog maintainers:

```bash
git clone https://github.com/arturonaredo/corsette.git
cd corsette
python3 -m pip install -e '.[dev]'

corsette validate
corsette scrub
python tools/check-skills.py
python tools/sync-packaged-runtime.py --check
python -m pytest packages/corsette/tests
```

Check that the three supported adapters generate without drift:

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

The packaged wheel contains a runtime snapshot so a PyPI installation can generate adapters without a Git checkout. [`tools/sync-packaged-runtime.py`](tools/sync-packaged-runtime.py) prevents this snapshot from drifting from canonical sources; [CI](.github/workflows/ci.yml) also installs a built wheel in isolation and exercises selective setup for all supported runtimes.

## Documentation and contribution

- [Contribution guide](CONTRIBUTING.md) — canonical layout, authoring conventions, installation details, validation, and release workflow.
- [Catalog](catalog/) — agents, skills, commands, model profiles, routing, and MCP definitions.
- [Knowledge index](okf/knowledge/index.md) — progressive-disclosure entry point for reusable OKF knowledge.
- [Adapters](adapters/README.md) — generated runtime layouts and adapter conventions.
- [Selective setup proposal](openspec/changes/remove-aicontext-and-add-selective-setup/proposal.md) and [requirements](openspec/changes/remove-aicontext-and-add-selective-setup/specs/selective-setup/spec.md) — the safety and behavior contract behind `corsette setup`.
- [PyPI publishing workflow](.github/workflows/pypi.yml) — trusted-publishing release automation.

Before opening a change, run the validation commands above and keep public catalog and OKF content reusable, English-oriented, and free of credentials, private infrastructure, or personal context.
