@ainova-systems/intelligence 0.11.0-rc.1 → 0.11.0-rc.10

package/packages/sync/references/adapters.md

@@ -0,0 +1,252 @@
+# Writing an Intelligence Adapter
+
+An adapter transforms tool-neutral rules, agents and skills into one tool's native files. The sync engine discovers adapters by filename and calls one shell function for each enabled target.
+
+## Built-in and project adapters
+
+| Location | Owner | Upgrade behavior |
+|---|---|---|
+| Installed CLI's `engine/adapters/` | Intelligence | Replaced when the CLI is upgraded |
+| `<content-dir>/adapters/` | Project | Never changed by CLI upgrades |
+
+The default content directory is `intelligence/`; `project.intelligence_dir` in `intelligence.yaml` may choose another. A project adapter with the same name as a built-in overrides it, and sync reports the override.
+
+Contribute broadly useful integrations as built-ins. Keep organization-specific or experimental formats in the project.
+
+## Create and enable an adapter
+
+Choose a lowercase shell-safe name matching `[a-z][a-z0-9_]*`, then scaffold from the template bundled with the installed engine:
+
+```bash
+intelligence adapter create mytool
+```
+
+This creates `<content-dir>/adapters/mytool.sh` and refuses to overwrite an existing file. Implement the generated functions, then enable its target:
+
+```bash
+intelligence adapter enable mytool
+```
+
+`adapter enable` adds or updates this manifest entry when the adapter exists, then runs a full sync so shared outputs such as `AGENTS.md` remain current:
+
+```yaml
+targets:
+  mytool: { enabled: true, output: ".mytool" }
+```
+
+Change `output` in `intelligence.yaml` if the tool expects another location. The engine validates the resolved path before calling the adapter.
+
+To stop syncing a target:
+
+```bash
+intelligence adapter disable mytool
+```
+
+Disabling changes only target state. Generated output is deliberately kept because a generic command cannot know which paths a custom adapter owns. Remove only documented owned paths after reviewing them. A disabled project adapter can be deleted with `intelligence adapter remove mytool`; removal prompts by default, accepts `--apply` for explicit non-interactive use, and also keeps generated output. Built-in adapter source cannot be removed. Use `intelligence adapter list` to inspect source, state and output.
+
+## Required function
+
+The file name and function name form the adapter's identity:
+
+```bash
+# <content-dir>/adapters/mytool.sh
+sync_to_mytool() {
+    local repo_root="$1"
+    local config_file="$2"
+    local output_dir="$3"
+
+    # transform sources into output_dir
+}
+```
+
+The engine calls:
+
+```text
+sync_to_<name> <repo-root> <absolute-intelligence.yaml> <absolute-output-path>
+```
+
+The engine has already loaded `engine/lib/common.sh` before it sources the adapter, so project adapters use its functions directly.
+
+## Source model
+
+`sources.rules`, `sources.agents` and `sources.skills` contain repo-relative directory paths. Packages have already been resolved, fetched and pinned by the CLI, so package content appears as an ordinary path under `.intelligence/packages/`. Adapters never perform network access or parse `packages:`.
+
+Iterate a source section in manifest order:
+
+```bash
+while IFS= read -r src; do
+    [ -n "$src" ] || continue
+    dir="$(resolve_source_dir "$repo_root" "$src")"
+    [ -d "$dir" ] || continue
+
+    for file in "$dir"/*.md; do
+        [ -f "$file" ] || continue
+        # transform file
+    done
+done < <(read_yaml_list "$config_file" "rules")
+```
+
+Later sources intentionally overwrite same-named artifacts from earlier sources. Package sources are wired before project sources, so project content can override a package artifact by name.
+
+## Shared functions
+
+Use the engine library instead of copying parsers or file-handling logic.
+
+| Function | Purpose |
+|---|---|
+| `resolve_source_dir(repo_root, source)` | Resolve a manifest source to its local directory. |
+| `read_yaml_list(config, section)` | Stream entries from `sources.<section>`. |
+| `get_frontmatter_value(key, file)` | Read a scalar from the first frontmatter block. |
+| `has_frontmatter(file)` / `has_paths(file)` | Inspect source shape. |
+| `strip_frontmatter(file)` | Emit the body without its first frontmatter block. |
+| `get_model(config, tool, tier)` | Resolve a `heavy`, `standard` or `light` model, including manifest overrides. |
+| `get_model_default(tool, tier)` | Read the built-in model default. |
+| `copy_skill_bundle(src, dest)` | Copy `SKILL.md` and all resources safely, normalize Markdown and quote free-text frontmatter. |
+| `sync_open_skill_dirs(root, config, dest)` | Own and populate a shared Agent Skills directory such as `.agents/skills/`. |
+| `finalize_output_file(file)` | Expand layout tokens and normalize line endings; required for every emitted text file. |
+| `get_target_field(config, target, field)` | Read another field from the target configuration. |
+| `repo_rel_link(root, path)` | Produce a stable repo-relative link for a committed output. |
+
+`lint_frontmatter` is run across all inputs by the engine before adapters execute. It warns about common YAML hazards; adapters should not duplicate that pass.
+
+## Rules, skills and agents
+
+### Rules
+
+Rules without `paths:` are always-on. Rules with `paths:` are scoped.
+
+Intelligence routes always-on rules once through `AGENTS.md` for tools that consume it. An adapter for such a tool should not copy those rules again. If the tool has a native scoped-rule channel, transform `paths:` to the tool's equivalent.
+
+| Built-in | Always-on rules | Scoped rules |
+|---|---|---|
+| `agents` | Inline in `AGENTS.md` | List with links |
+| `claude` | Copy | Copy with `paths:` preserved |
+| `cursor` | Omit; reads `AGENTS.md` | `.mdc` with `globs:` |
+| `copilot` | Omit; reads `AGENTS.md` | `.instructions.md` with `applyTo:` |
+| `codex` | Omit; reads `AGENTS.md` | No native channel |
+| `pi` | Omit; reads `AGENTS.md` | Generated on-demand files and extension |
+| `opencode` | Omit; reads `AGENTS.md` | No native channel |
+
+If a new adapter relies on `AGENTS.md` for always-on rules, its target must require `agents`. Add that invariant to `engine/sync.sh` when contributing the adapter upstream.
+
+### Skills
+
+Skills follow the [Agent Skills standard](https://agentskills.io). Copy each skill directory as a complete bundle—not only `SKILL.md`—because its body may reference `references/`, `scripts/` or `assets/` beside it.
+
+```bash
+copy_skill_bundle "$source_skill_dir" "$output_dir/skills/$skill_name"
+```
+
+Do not use plain `cp` for skill bundles. `copy_skill_bundle` preserves non-Markdown assets, avoids materializing symlink targets, normalizes Markdown, expands layout tokens and quotes `description` and `argument-hint` where strict YAML readers require strings.
+
+Codex, Pi and OpenCode share `.agents/skills/`. Any adapter writing that open-standard directory must call `sync_open_skill_dirs`; it is the single lifecycle owner for immediate skill subdirectories.
+
+### Agents
+
+Source agents use tool-neutral fields:
+
+```yaml
+---
+name: backend-developer
+description: "Implements backend features"
+tier: heavy
+access: full
+---
+```
+
+Map `tier` through `get_model`, not a hardcoded model name. Transform `access: full|readonly` into the target tool's native permission model. Preserve the body as the agent's instructions.
+
+Built-ins currently emit Claude and Cursor Markdown, Copilot `.agent.md`, Codex TOML, Pi prompt templates and OpenCode Markdown subagents. Read the closest built-in adapter before implementing a new transformation.
+
+## Layout tokens
+
+Content shipped in `@ainova-systems/sync` cannot assume the project's content-directory name or package-store location. It uses these tokens:
+
+| Token | Expansion |
+|---|---|
+| `<content-dir>` | Project content directory, usually `intelligence` |
+| `<module>` | Installed sync package, usually `.intelligence/packages/@ainova-systems/sync` |
+| `<manifest>` | `intelligence.yaml` |
+| `<sync-cmd>` | `intelligence sync` |
+
+Call `finalize_output_file` on every text file after transformation. It expands the tokens literally and converts CRLF to LF. A generated file containing an unexpanded token is an adapter bug.
+
+`copy_skill_bundle` already finalizes Markdown within a skill; do not run a second custom token pass.
+
+## Cleanup and safety contract
+
+Adapters regenerate output, so cleanup is part of their public contract.
+
+1. Delete only paths the adapter owns. Preserve sibling settings, commands, extensions, workflows and hand-authored files.
+2. Make ownership obvious in `sync_to_<name>()`; the same list is what a user removes after disabling or uninstalling the adapter.
+3. Use marker-based cleanup when generated and hand-authored files share a directory. The OpenCode adapter is the reference implementation.
+4. Use `sync_open_skill_dirs` for `.agents/skills/`; multiple adapters share it.
+5. Write only beneath the supplied `output_dir`, except for an explicitly shared standard path handled by a shared helper.
+6. Make repeated syncs idempotent.
+
+Before an adapter runs, the engine canonicalizes and validates its configured output. It refuses the repository root, paths outside the repository, symlink escapes, the project content directory, `.intelligence/` and configured source paths. This guard does not make broad cleanup safe: an adapter must still avoid deleting unrelated files within a valid tool directory.
+
+## Minimal example
+
+This example copies rules without frontmatter. A real adapter must decide how the target represents scoping and should also implement agents and skills.
+
+```bash
+#!/bin/bash
+
+sync_mytool_rules() {
+    local repo_root="$1" config_file="$2" output_dir="$3"
+    mkdir -p "$output_dir/rules"
+
+    while IFS= read -r src; do
+        [ -n "$src" ] || continue
+        local dir
+        dir="$(resolve_source_dir "$repo_root" "$src")"
+        [ -d "$dir" ] || continue
+
+        for file in "$dir"/*.md; do
+            [ -f "$file" ] || continue
+            strip_frontmatter "$file" > "$output_dir/rules/$(basename "$file")"
+            finalize_output_file "$output_dir/rules/$(basename "$file")"
+        done
+    done < <(read_yaml_list "$config_file" "rules")
+}
+
+sync_to_mytool() {
+    local repo_root="$1" config_file="$2" output_dir="$3"
+
+    rm -rf "$output_dir/rules"
+    sync_mytool_rules "$repo_root" "$config_file" "$output_dir"
+}
+```
+
+## Testing
+
+Use a disposable Git repository with an Intelligence manifest and representative always-on/scoped rules, agents, skills and bundled skill resources.
+
+```bash
+intelligence sync mytool
+```
+
+Verify:
+
+- native file names, frontmatter and model/permission mappings;
+- scoped and always-on routing without duplicated context;
+- skill resources are present;
+- no literal layout tokens remain;
+- hand-authored siblings under the tool root survive;
+- output paths cannot overlap sources or escape the repository;
+- a second sync produces no Git diff.
+
+For a built-in adapter, add the same assertions to the repository's smoke or lifecycle tests and run all five CLI suites before submitting the change.
+
+## Built-in outputs
+
+| Adapter | Primary output |
+|---|---|
+| `agents` | `AGENTS.md` |
+| `claude` | `.claude/rules`, `.claude/agents`, `.claude/skills` |
+| `cursor` | `.cursor/rules`, `.cursor/agents`, `.cursor/skills` |
+| `copilot` | `.github/instructions`, `.github/agents`, `.github/skills` |
+| `codex` | `.codex/agents`, `.agents/skills` |
+| `pi` | `.pi/intelligence-sync`, `.pi/extensions`, `.pi/prompts`, `.agents/skills` |
+| `opencode` | `.opencode/agents`, marker-owned `.opencode/commands`, `.agents/skills` |

package/packages/sync/references/conventions.md

@@ -0,0 +1,385 @@
+# Intelligence Authoring Conventions
+
+Intelligence stores project-owned AI rules, agents and skills as tool-neutral Markdown. The CLI installs shared packages, and the sync engine renders each enabled target's native files.
+
+## Choose the right artifact
+
+| Type | Intent | Loading | Content |
+|---|---|---|---|
+| **Rule** | The model respects a constraint or convention | Automatic: always-on or path-scoped | Required patterns, invariants, architecture and examples |
+| **Skill** | The model performs a procedure | Explicit invocation | Ordered steps, decisions and verification |
+| **Agent** | The model adopts a role or expertise boundary | Explicit selection or skill binding | Expertise, boundaries and build/verify behavior |
+
+Use these tests:
+
+- “The model should consider this during every task in scope” → rule.
+- “The model should execute these steps” → skill.
+- “The model should reason as this specialist” → agent.
+
+Do not bury conventions in agents, workflows in rules or reusable expertise in skills. Each misplaced concern either fails to load when needed or consumes context when it is not needed.
+
+## Intelligence project structure
+
+```text
+project/
+├── intelligence.yaml       # root manifest and schema_version contract
+├── intelligence.lock       # resolved packages; commit it
+├── intelligence/           # project-owned content; name is configurable
+│   ├── rules/
+│   │   ├── context.md
+│   │   └── backend.md
+│   ├── agents/
+│   │   └── backend-developer.md
+│   ├── skills/
+│   │   └── backend-add-endpoint/
+│   │       └── SKILL.md
+│   └── adapters/           # optional project adapters
+│       └── mytool.sh
+├── .intelligence/          # CLI-managed package store; gitignored
+│   └── packages/
+│       └── @scope/name/
+├── AGENTS.md               # generated canonical context; normally committed
+└── .claude/ .cursor/ ...   # generated tool-native output
+```
+
+The content directory defaults to `intelligence/`. A project may set `project.intelligence_dir` in `intelligence.yaml`; never infer or hardcode the default when the manifest is available.
+
+Project-authored rules, agents, skills and adapters live in the content directory. Installed package content lives under `.intelligence/packages/` and is replaced by CLI lifecycle/package operations; edit it only in its source repository. The executable engine remains with the installed CLI, outside the project.
+
+The `intelligence-` name prefix is reserved for artifacts shipped by `@ainova-systems/sync`. Project artifacts use their project or domain prefix.
+
+## Manifest, packages and sources
+
+The engine consumes ordinary local source paths:
+
+```yaml
+project:
+  name: payments
+  intelligence_dir: "intelligence"  # optional; this is the default
+
+schema_version: "0.11.0"
+
+sources:
+  rules:
+    - ".intelligence/packages/@ainova-systems/sync/rules"
+    - "intelligence/rules"
+  agents:
+    - ".intelligence/packages/@ainova-systems/sync/agents"
+    - "intelligence/agents"
+  skills:
+    - ".intelligence/packages/@ainova-systems/sync/skills"
+    - "intelligence/skills"
+```
+
+Missing project-owned source directories are skipped, so a package-only project need not create empty `rules/`, `agents/` or `skills/` directories. Source order matters: later files with the same artifact name overwrite earlier ones. Package sources are wired before project sources so the project can override a package artifact deliberately.
+
+The CLI owns package and registry blocks:
+
+```yaml
+packages:
+  "@acme/backend":
+    version: "^1.2.0"
+
+registries:
+  - "https://github.com/acme/intelligence-registry.git"
+```
+
+Do not put Git URLs or remote tokens directly in `sources:`. Use:
+
+```bash
+intelligence package add @acme/backend
+intelligence package add github:acme/backend-intelligence
+intelligence package add 'git+https://git.example.com/acme/backend.git@main#package'
+```
+
+Registries are an ordered trust list and the only resolver for a package name. There is no built-in catalog and no `@org/name` → GitHub guessing. An explicit `github:` or `git+` spec bypasses registry lookup. In every case the manifest stores only requested `version` or `ref`; resolved URL/path and SHA live in the lock.
+
+Stable Git tags provide package versions. Semver ranges select the highest matching stable tag; a `ref:` pin names a branch or commit and does not move during `intelligence update`. One package name has one version per project.
+
+Commit `intelligence.lock`. It records requested versions, source URLs and paths, resolved refs and commit SHAs. After cloning, `intelligence sync` restores a missing store strictly from that lock before rendering; manifest/lock or SHA drift is refused. Re-run `package add` when deliberately changing a source.
+
+`@ainova-systems/sync` is ordinary package content exact-pinned to the bundled engine version. `intelligence init` installs it unless `--bare` is used. Lifecycle preflight keeps that pin and `schema_version` aligned with the installed CLI; package-range updates never move it independently.
+
+## Layout tokens
+
+Package-owned artifacts cannot assume the project's content-directory name or their installed package path. They use tokens expanded by every adapter through `finalize_output_file`:
+
+| Token | Expansion |
+|---|---|
+| `<content-dir>` | Repo-relative content directory, usually `intelligence` |
+| `<module>` | Installed sync package, usually `.intelligence/packages/@ainova-systems/sync` |
+| `<manifest>` | `intelligence.yaml` |
+| `<sync-cmd>` | `intelligence sync` |
+
+Expansion applies to frontmatter and bodies. Thus `paths: ["<content-dir>/**"]` reaches every native scoped-rule format with the project's real directory name.
+
+Project-authored artifacts normally use their known project paths directly. Tokens are useful only when the same artifact must work under different content-directory or package-store locations.
+
+## Naming
+
+Rule filenames, agent names and skill names share a domain prefix such as `backend-`, `frontend-`, `devops-`, `core-`, `tests-`, a project codename or a monorepo component. Pick the domain from repository structure and reuse it.
+
+- Skills: `<domain>-<verb>-<noun>`, for example `backend-add-endpoint`.
+- Agents: `<domain>-<role>`, for example `backend-code-reviewer`.
+- Rules: `<domain>.md`, for example `backend.md`.
+
+Common skill verbs:
+
+| Verb | Meaning |
+|---|---|
+| `add-` | Add one member to an existing set |
+| `create-` | Create a new container or top-level artifact |
+| `update-` | Revise existing state selectively |
+| `run-` | Execute an operation |
+| `review-` | Perform read-only analysis |
+| `test-` | Verify behavior |
+| `remove-` | Remove an artifact safely |
+
+The verb describes the outcome, not whether the skill implements the work or delegates to another command or skill.
+
+## Agent conventions
+
+```yaml
+---
+name: backend-developer
+description: "Implements backend features"
+tier: heavy
+access: full
+skills:
+  - backend-add-endpoint
+---
+
+# Backend developer
+
+Agent instructions in Markdown.
+```
+
+An agent stays thin: **Expertise** → **Boundaries** → **Build & Verify**. Its role, limits and proof of completion belong here; reusable constraints belong in rules and reusable procedures belong in skills.
+
+Do not instruct an agent to read rules or restate their content. Claude loads its generated rules for its subagents, while Cursor, Copilot, Codex, Pi and OpenCode receive always-on rules through `AGENTS.md`. Duplicating a rule in an agent spends context twice and creates a copy that drifts.
+
+### Tier mappings
+
+| Tier | Claude | Cursor | Copilot / Codex | OpenCode | Typical use |
+|---|---|---|---|---|---|
+| `heavy` | `opus` | `inherit` | `gpt-5.6-sol` | `anthropic/claude-opus-4-8` | implementation, complex reasoning, migration |
+| `standard` | `sonnet` | `inherit` | `gpt-5.6-terra` | `anthropic/claude-sonnet-5` | review, validation, analysis |
+| `light` | `haiku` | `fast` | `gpt-5.6-luna` | `anthropic/claude-haiku-4-5-20251001` | lookups and simple formatting |
+
+The vocabulary is tool-neutral. Adapters resolve it through `get_model()`. Override a default under `models.<tool>.<tier>` in `intelligence.yaml` only when the project needs a pin; sync reports drift when that override differs from the current default.
+
+### Access mappings
+
+`access: full` inherits ordinary tool permissions. `access: readonly` is transformed into the target's native restriction: for example Claude receives read/search/bash tools with writes disallowed, Cursor receives `readonly: true`, and Codex receives a read-only sandbox.
+
+Use only `full` or `readonly` in source agents. Tool-specific permission syntax belongs in adapters.
+
+## Rule conventions
+
+```yaml
+---
+paths:
+  - "src/backend/**"
+  - "config/**"
+description: "Backend conventions"
+---
+
+# Backend conventions
+
+Rule content in Markdown.
+```
+
+`paths:` is optional:
+
+- With `paths:`, the rule is scoped to matching repository files.
+- Without `paths:`, the rule is always-on project context.
+
+### Routing
+
+| Source rule | Claude | Cursor | Copilot | Codex / Pi / OpenCode / `AGENTS.md` |
+|---|---|---|---|---|
+| Scoped | copied with `paths:` | `.mdc` with `globs:` | `.instructions.md` with `applyTo:` | listed in `AGENTS.md`; Pi also gets on-demand files and an extension |
+| Always-on | copied | omitted | omitted | inlined once into `AGENTS.md` |
+
+Cursor, Copilot, Codex, Pi and OpenCode consume `AGENTS.md`, so always-on rules are not duplicated in their tool-specific channels. Claude does not consume `AGENTS.md`, so it receives the full rule set. OpenCode and Codex have no generated path-scoped rule channel; OpenCode users may configure `instructions:` globs themselves.
+
+Keep always-on rules small. Put narrow framework or component guidance behind `paths:` so unrelated tasks do not pay its context cost.
+
+## Skill conventions
+
+Skills follow the [Agent Skills standard](https://agentskills.io). Required fields are `name` and `description`.
+
+```yaml
+---
+name: backend-add-endpoint
+description: "Add a backend endpoint"
+argument-hint: "<route-name>"
+---
+
+# Add a backend endpoint
+
+1. Inspect the existing route pattern.
+2. Implement the endpoint.
+3. Run focused tests.
+4. Report the changed route and verification.
+```
+
+Standard optional fields (`license`, `compatibility`, `metadata`, `allowed-tools`) and tool extensions pass through unchanged. A tool ignores fields it does not understand.
+
+These limits reject a skill instead of degrading it:
+
+| Field | Limit | Failure mode |
+|---|---|---|
+| `name` | 64 characters | Rejected at load |
+| `description` | 1024 characters | Rejected at load |
+| `argument-hint` | Must be a string | An unquoted `[value]` is parsed as a YAML sequence |
+
+Sync quotes free-text `description` and `argument-hint` values in generated copies. `lint_frontmatter` warns when a name or description exceeds its hard limit, but the author must shorten it.
+
+### Description budget
+
+Descriptions share the tool's available-artifact context budget.
+
+| Case | Format | Target |
+|---|---|---|
+| Unique skill | Plain verb–noun phrase | 4–8 words |
+| Similar sibling skills | Verb–noun plus a distinguishing trigger | 10–20 words, roughly 250 characters or less |
+
+The 1024-character limit is a rejection wall, not a writing target. Curate duplicate and orphaned artifacts before compressing every description into ambiguity.
+
+### Skill body and resources
+
+A skill that performs work carries the decisions and verification needed for that work. A skill that dispatches to deterministic CLI behavior stays thin: it chooses the command, interprets status and adds only judgment that the program cannot provide.
+
+Keep on-demand detail beside the skill:
+
+```text
+skill-name/
+├── SKILL.md
+├── references/    # detailed material loaded only when needed
+├── scripts/       # deterministic or repetitive helpers
+└── assets/        # templates and output resources
+```
+
+The engine copies the complete skill directory. Promote a helper outside the skill only when multiple skills share it.
+
+Size limits are backstops, not quotas:
+
+| Artifact | Hard cap | Response |
+|---|---|---|
+| `SKILL.md` body | 1000 lines | Move detail to `references/` |
+| Reference file | 500 lines | Add a contents list past 300; split if still oversized |
+| Rule | 500 lines | Split by scope or move examples behind a skill reference |
+| Agent | 200 lines | Move procedures and constraints into skills/rules |
+
+## Writing discipline
+
+- Use imperative form: “Read the manifest,” not “You should read the manifest.”
+- Explain why a decision rule exists so the model can apply it to adjacent cases.
+- Reserve absolute language for genuine safety, security and output-format invariants.
+- Lead with the positive behavior; keep anti-patterns after the actionable guidance.
+- Remove instructions that repeat tool defaults, repository facts already discoverable from files, or another artifact.
+- Turn repeated deterministic work into a script or CLI command and let the skill interpret it.
+
+Every line enters a finite context budget. Prefer subtraction, consolidation and precise scope over exhaustive prose.
+
+## Generated output
+
+| Target | Rules | Skills | Agents |
+|---|---|---|---|
+| `agents` | Always-on inlined; scoped listed in `AGENTS.md` | Listed | Listed |
+| Claude | `.claude/rules/` | `.claude/skills/` | `.claude/agents/` |
+| Cursor | scoped `.cursor/rules/*.mdc` | `.cursor/skills/` | `.cursor/agents/` |
+| Copilot | scoped `.github/instructions/*.instructions.md` | `.github/skills/` | `.github/agents/` |
+| Codex | `AGENTS.md` only | `.agents/skills/` | `.codex/agents/*.toml` |
+| Pi | `AGENTS.md` plus scoped `.pi/intelligence-sync/rules/` | `.agents/skills/` | `.pi/prompts/intelligence-agent-*.md` |
+| OpenCode | `AGENTS.md` only | `.agents/skills/` plus slash commands | `.opencode/agents/*.md` |
+
+`AGENTS.md` is regenerated by the `agents` adapter. Its optional static header is `targets.agents.header` in `intelligence.yaml`; generated rule, agent and skill sections follow it. Commit `AGENTS.md` when it is the project's shared canonical context.
+
+Generated IDE output may be gitignored when every collaborator can reproduce it with `intelligence sync`. Use narrow ownership patterns so hand-authored tool settings remain trackable:
+
+```gitignore
+# CLI-managed package store
+.intelligence/
+
+# Generated Claude and Cursor content; settings remain trackable
+.claude/rules/
+.claude/agents/
+.claude/skills/
+.cursor/rules/
+.cursor/agents/
+.cursor/skills/
+
+# Generated open-standard and Codex content
+.agents/
+.codex/agents/
+
+# Generated Pi content
+.pi/intelligence-sync/
+.pi/extensions/intelligence-sync-rules.ts
+.pi/prompts/intelligence-agent-*.md
+
+# Generated OpenCode agents. Its commands directory may also contain
+# hand-authored files, so choose per-project ignores there.
+.opencode/agents/
+```
+
+Copilot output lives under `.github/`; choose whether to commit it with other repository-level GitHub configuration. Do not ignore `.github/` wholesale.
+
+## Project-owned adapters
+
+Create a project adapter with:
+
+```bash
+intelligence adapter create mytool
+# implement <content-dir>/adapters/mytool.sh
+intelligence adapter enable mytool
+```
+
+Project adapters survive CLI upgrades and may override a built-in by name. `intelligence adapter enable mytool` runs a full sync so shared context stays current. `intelligence adapter disable mytool` keeps generated output for explicit, adapter-aware cleanup; a disabled project adapter can then be deleted with `intelligence adapter remove mytool`. See `adapters.md` for the function, ownership and safety contracts.
+
+## Schema and command boundaries
+
+The permanent applied-schema key is the top-level scalar `schema_version` in `intelligence.yaml`. It is not a dotfile and not the CLI package version. Do not rename, move or reshape this key: every engine must be able to decide compatibility before parsing the rest of the manifest.
+
+The public lifecycle is deliberately compact:
+
+- `intelligence init [--preview|--apply]` is universal: it creates a new setup, aligns an existing Intelligence project, or plans/applies conversion of an eligible legacy Intelligence Sync project.
+- `intelligence sync [adapter]` first aligns an existing Intelligence project with the installed CLI, restores a missing store strictly from `intelligence.lock`, then renders. In CI it refuses an alignment that would change tracked files and points to a local `intelligence init --apply` plus review/commit.
+- `intelligence update [@scope/name] [--preview|--apply]` is the only update surface. It prints the CLI/project/package plan; default mode prompts, `--preview` never writes, and `--apply` does not prompt. It never moves `ref:` pins.
+- `intelligence package add|remove|list|search` owns package inventory.
+- `intelligence adapter list|create|enable|disable|remove` owns adapter inventory and target state.
+- `intelligence status [--check]` reports state; `--check` runs deep consistency checks.
+
+Implement Intelligence schema changes as idempotent structural checks. Stage and verify replacement state before deleting or replacing prior state. A stale engine refuses a manifest whose `schema_version` is newer; normal project entry points close a behind-project gap through lifecycle preflight.
+
+Breaking changelog entries use a `### Breaking` checklist of verifiable post-conditions. The update skill reads every release across the version gap, chooses the package/CLI/project command sequence and verifies those conditions after the deterministic command completes.
+
+### Engine status contract
+
+The engine emits one machine-readable line, `IS_STATUS=<code> [IS_DETAIL=...]`, and exits with a stable code:
+
+| `IS_STATUS` | Exit | Meaning |
+|---|---:|---|
+| `ok` | 0 | Sync or operation completed |
+| `migrated` | 0 | Initialization converted an older layout |
+| `error` | 1 | Generic failure |
+| `config-missing` | 2 | Required manifest is absent |
+| `ambiguous` | 3 | Conflicting state requiring agent/human judgment; reserved |
+| `ahead-of-engine` | 4 | Manifest schema is newer than the engine |
+| `aborted-incomplete` | 5 | Staged replacement was incomplete; prior state remains |
+| `needs-update` | 6 | Project schema is behind the engine; rerun through a public lifecycle command |
+
+Callers capture the real code with `command || rc=$?`. Do not use `if ! command; then rc=$?`; inside that branch `$?` is the status of the negation.
+
+## Project entry points
+
+| Path | Role | Git status |
+|---|---|---|
+| `intelligence.yaml` | Manifest and schema contract | Tracked |
+| `intelligence.lock` | Resolved package state | Tracked |
+| `<content-dir>/{rules,agents,skills,adapters}/` | Project source of truth | Tracked |
+| `.intelligence/` | Restorable package store | Ignored |
+| `AGENTS.md` | Generated canonical project context | Normally tracked |
+| Tool output directories | Generated native content | Project policy; use narrow ignores |