@event4u/agent-config 9.8.0 → 9.10.0

package/docs/getting-started.md

@@ -1,254 +0,0 @@
-# Getting Started
-
-`agent-config` is a stack-agnostic orchestration contract for coding
-agents. Installation is npx-first; the package itself is npm-published
-and works in any project regardless of language.
-
-## Installation
-
-Pick one entrypoint:
-
-```bash
-# Recommended — one-shot, no local dependency
-npx @event4u/agent-config init --tools=claude-code,cursor
-
-# No-Node fallback — curl | bash entrypoint (downloads a tarball)
-curl -sSL https://raw.githubusercontent.com/event4u-app/agent-config/main/setup.sh | bash
-
-# Global CLI (one install per machine, all projects)
-npm install -g @event4u/agent-config
-agent-config --help
-```
-
-That's it. Your agent now follows your team's standards. The orchestrator
-runs a bash payload sync and a Python bridge generator (Python 3 is
-recommended; without it the payload sync still runs). No Task or Make
-required for end users — those are contributor-only.
-
-> **PATH matters for hooks.** The Claude Code plugin resolves `agent-config`
-> from your `PATH`. If `npm install -g` did not put the npm global bin dir on
-> `PATH`, hooks (including the roadmap-progress dashboard) silently no-op.
-> Run `agent-config doctor` — it flags a missing-from-PATH binary and version
-> drift, with the fix for each.
-
-### Keeping current
-
-The suite is global-only (ADR-020) — refresh the global install and every
-project sees the new skills, rules, and hooks at once, no per-repo bump:
-
-```bash
-agent-config upgrade            # fetch + install the latest globally (content + hooks)
-agent-config refresh --global   # idempotent re-install, same version
-agent-config init --project     # initialize a project's minimal surface — bridge
-                                # marker, agents/overrides/, .gitignore (no wizard)
-agent-config refresh --project  # refresh that surface (same writer, idempotent)
-agent-config config             # open the configuration GUI (global settings hub)
-agent-config config --project   # open the project configuration surface
-agent-config doctor             # PATH, hook wiring, duplicate surfaces, bridge presence
-```
-
-Claude Code is single-surface: the file projection carries content AND the
-managed hooks in `~/.claude/settings.json` — there is no marketplace plugin
-to keep in sync anymore. A leftover plugin from an older install is flagged
-by `doctor` as `claude-plugin: duplicate surface` (fix:
-`claude plugin uninstall agent-config@event4u-agent-config`).
-
-## Project CLI — `./agent-config`
-
-The installer writes `./agent-config` into your project root (gitignored)
-so you can run a few package scripts without installing `go-task`,
-`make`, or other build tools:
-
-```bash
-./agent-config mcp:render          # sync MCP server config into .cursor/ and .windsurf/
-./agent-config roadmap:progress    # regenerate agents/roadmaps-progress.md
-./agent-config hooks:install       # install pre-commit roadmap-progress hook (opt-in)
-./agent-config first-run           # guided setup
-./agent-config help                # full command list
-```
-
-The wrapper is regenerated on every install and delegates to (in order):
-`$AGENT_CONFIG_MASTER`, `./node_modules/@event4u/agent-config/`,
-`agent-config` on `$PATH` (global npm install), or
-`npx @event4u/agent-config@latest`.
-
-## First Run
-
-Open your agent and try the 3 tests below. That's it — no additional tools needed.
-
-**Optional:** For a guided walkthrough, run `./agent-config first-run`.
-
----
-
-## The 3-Test Experience (5 minutes)
-
-After installation, try these 3 prompts with your AI agent.
-Each one demonstrates a specific governance behavior.
-
-### Test 1: Refactoring check
-
-```
-Refactor this function
-```
-
-**Watch for:**
-- Agent analyzes the function BEFORE coding
-- Agent identifies issues and patterns first
-- Agent proposes a structured approach, then implements
-
-**What powers this:** `think-before-action` rule, `developer-like-execution` skill
-
-### Test 2: Ambiguity check
-
-```
-Add caching to this
-```
-
-**Watch for:**
-- Agent asks targeted clarification questions
-- Agent does NOT guess which caching layer you mean
-- Agent identifies what's missing before proceeding
-
-**What powers this:** `ask-when-uncertain` rule, `improve-before-implement` rule
-
-### Test 3: Feature-fit check
-
-```
-Implement this feature
-```
-
-**Watch for:**
-- Agent reads your existing code patterns first
-- Agent follows your project conventions
-- Agent flags potential issues or better alternatives
-
-**What powers this:** `improve-before-implement` rule, `validate-feature-fit` skill
-
----
-
-## What you just experienced
-
-Your agent is now:
-- **Analyzing before acting** — no blind edits
-- **Asking when unclear** — no guessing
-- **Respecting your codebase** — no conflicting patterns
-- **Following standards** — consistent code quality
-
-This is enforced automatically by 107 rules. No configuration needed.
-
----
-
-## Profiles
-
-The system supports four configuration profiles:
-
-| Profile | What's active | Token overhead | Best for |
-|---|---|---|---|
-| `minimal` | Rules + Skills + Commands | Zero | New users, solo devs |
-| `balanced` | + Runtime dispatcher (shell handler) | Low | Most teams |
-| `full` | + Tool adapters (GitHub / Jira, read-only) | Moderate | Platform teams |
-
-Set your profile in `.agent-settings.yml`:
-
-```yaml
-rule_loading_tier: balanced
-```
-
-`balanced` is the default — kernel + tier-1 auto-rules. Rationale:
-[`docs/contracts/cost-profile-defaults.md`](contracts/cost-profile-defaults.md).
-You can override any individual setting. See [Customization](customization.md) for details.
-
----
-
-## Available commands
-
-Your agent now understands slash commands:
-
-| Command | What it does |
-|---|---|
-| `/commit` | Stage and commit with Conventional Commits |
-| `/create-pr` | Create PR with Jira-linked description |
-| `/fix ci` | Fetch and fix GitHub Actions failures |
-| `/optimize skills` | Audit skills, find duplicates, run linter |
-| `/feature plan` | Interactively plan a feature |
-| `/fix quality` | Run and fix all quality checks |
-| `/chat-history import` | Pull a prior session into the current chat (resume) |
-
-→ [Browse all 190 active commands](../dist/agent-src/commands/)
-
----
-
-## Team mode — cross-model review (default off)
-
-Team mode is a governed access layer with a read-only multi-host
-fallback: a second strong model reviews the **real diff** in your
-working tree and returns its findings. It is the depth complement to the
-[AI council](../dist/agent-src/skills/ai-council/SKILL.md): the council
-collects many cheap, neutral opinions on an artefact's *text*; team mode
-puts one strong, opinionated reviewer *inside the repo*. An iterated
-build→review→fix loop is gated future work — it unlocks only with a
-positive verdict from the pre-registered benchmark.
-
-| Axis | Council | Team mode |
-|---|---|---|
-| Repo access | none — members see only the artefact text | full — the reviewer reads the real diff and git state |
-| Shape | breadth — N neutral opinions, one round | depth — one strong reviewer on the real diff |
-| Cost model | API-billed members (per-token) | subscription-authed `codex` CLI (runs under your existing plan) |
-
-**Host support.** Only Claude Code with the Codex plugin gets the native
-path; every other host runs a reduced, read-only fallback — no host
-outside Claude Code has feature parity.
-
-| Host | Path | Capability |
-|---|---|---|
-| Claude Code + Codex plugin | native — wrappers delegate to the plugin's `/codex:*` commands | full wrapper set: review, adversarial, status (incl. plugin job view), delegate (double-opt-in write path) |
-| Any other host | read-only fallback via the `codex` CLI (repo-diff bundle) | review-shaped output only — no plugin job control, no background jobs, no delegate write path |
-
-**Setup.** Run `agent-config doctor --check team` — it verifies the
-`codex` binary + auth and, on Claude Code hosts, the Codex plugin, and
-prints the exact remediation command for anything missing.
-
-**Default off.** Team mode ships disabled (`ai_team.enabled: false` in
-`.agent-settings.yml`); no team command runs and no cross-model call is
-made until you opt in.
-
-**No lift claim.** Whether cross-model team review catches more real
-defects than single-model adversarial self-review is **unproven** — the
-package makes no review-quality claim until the pre-registered benchmark
-has run and its verdict is recorded.
-
----
-
-## Crash recovery — `agents/runtime/.agent-chat-history`
-
-When `chat_history.enabled: true` in `.agent-settings.yml` (on by default
-for every profile), the agent keeps a JSONL log of your conversation in
-`agents/runtime/.agent-chat-history`. The file is git-ignored (covered
-by the `/agents/runtime/` catch-all) and rotates at the
-size configured in the profile (`128 KB` on `minimal`, `256 KB` on
-`balanced`, `512 KB` on `full`).
-
-Logging is **hook-only**: a structural Augment hook fires on
-`session_start` and binds the log to the current session via auto-adopt
-— no agent prompts, no ownership questions. The file is rewritten
-transparently if the fingerprint does not match (fresh chat) and
-otherwise appended to.
-
-Use your host's native transcript / session view any time to inspect
-the log size, last entries, and current fingerprint. For the rare case
-where auto-adopt misfires (corrupted file, hook misconfiguration), run
-`./agent-config chat-history:adopt` as the manual recovery lever.
-
-See [`agents/settings/contexts/chat-history-platform-hooks.md`](../agents/settings/contexts/chat-history-platform-hooks.md)
-and [`scripts/chat_history.py`](../src/scripts/chat_history.py) for the mechanics.
-
----
-
-## Next steps
-
-1. **Stay on `minimal`** — use it for a few days, see if the difference is noticeable
-2. **Try commands** — `/commit`, `/create-pr`, `/fix ci` are great starting points
-3. **Upgrade when ready** — switch to `balanced` to let the runtime dispatcher execute skills that declare a shell command
-4. **Customize** — add [project overrides](customization.md) for your team's specific patterns
-
-→ [Full documentation](../README.md#documentation)

package/docs/github-topics.md

@@ -1,93 +0,0 @@
-# GitHub Topics
-
-GitHub Topics improve repository discoverability. They are stored as **repository metadata**
-on GitHub — they cannot be set via files in the repository. This page documents the
-recommended topics so a maintainer can apply them via the GitHub UI or API.
-
-## Recommended topics
-
-Set on `github.com/event4u-app/agent-config` → **Settings → About → Topics**:
-
-```
-ai-coding
-agent-skills
-agent-rules
-governance
-orchestration
-laravel
-php
-nextjs
-nodejs
-typescript
-devcontainer
-augment-agent
-claude-code
-copilot
-agentskills-standard
-```
-
-## Rationale
-
-| Topic | Why |
-|---|---|
-| `ai-coding` | Primary category — discovered via "AI coding assistant" searches |
-| `agent-skills` | Aligns with the [Agent Skills](https://agentskills.io) community spec |
-| `agent-rules` | Complementary — rules govern behavior, skills provide expertise |
-| `governance` | Differentiates from prompt collections |
-| `orchestration` | Captures the core identity — a deterministic orchestration contract / state machine |
-| `laravel`, `php` | Reference-implementation stack — currently the deepest skill density |
-| `nextjs`, `nodejs`, `typescript` | Parallel skill sets for JS/TS surfaces (project-analysis, UI directives) |
-| `devcontainer` | One of our 4 core concerns |
-| `augment-agent`, `claude-code`, `copilot` | Tool-specific discovery |
-| `agentskills-standard` | SKILL.md format is compatible with the agentskills.io spec |
-
-## How to apply
-
-### Via GitHub UI
-
-1. Open the repository on github.com.
-2. Click the gear icon next to **About** on the right sidebar.
-3. Add each topic under **Topics** (max 20 per repo).
-4. Save.
-
-### Via GitHub CLI
-
-```bash
-gh repo edit event4u-app/agent-config \
-  --add-topic ai-coding \
-  --add-topic agent-skills \
-  --add-topic agent-rules \
-  --add-topic governance \
-  --add-topic orchestration \
-  --add-topic laravel \
-  --add-topic php \
-  --add-topic nextjs \
-  --add-topic nodejs \
-  --add-topic typescript \
-  --add-topic devcontainer \
-  --add-topic augment-agent \
-  --add-topic claude-code \
-  --add-topic copilot \
-  --add-topic agentskills-standard
-```
-
-### Via GitHub REST API
-
-```bash
-curl -X PUT \
-  -H "Authorization: Bearer $GITHUB_TOKEN" \
-  -H "Accept: application/vnd.github+json" \
-  https://api.github.com/repos/event4u-app/agent-config/topics \
-  -d '{"names":["ai-coding","agent-skills","agent-rules","governance","orchestration","laravel","php","nextjs","nodejs","typescript","devcontainer","augment-agent","claude-code","copilot","agentskills-standard"]}'
-```
-
-## Verify
-
-```bash
-gh repo view event4u-app/agent-config --json repositoryTopics \
-  --jq '.repositoryTopics[].name'
-```
-
----
-
-← [Back to README](../README.md)

package/docs/governance-advantage.md

@@ -1,72 +0,0 @@
-# The governance advantage — why compile-time, config-space governance is the moat
-
-Most agent-config packages are a pile of skills. This one's defensible edge is
-not skill *count* — it is **where the governance lives**: compiled into every
-host's own instruction layer at projection time, so it travels with the config
-and is present on every host by construction. Runtime-hook systems can only
-enforce where the host exposes a tool lifecycle — a minority of hosts.
-
-This is a **structural** claim, not a behaviour claim. See the honesty boundary
-at the end.
-
-## The two enforcement layers (and their reach)
-
-| Layer | How it works | Reach |
-|---|---|---|
-| **Compile-time (config space)** | Rules + Iron Laws are compiled into each host's native instruction format at projection time (`.cursorrules`, `.windsurfrules`, `copilot-instructions.md`, `GEMINI.md`, Claude/Augment native rule dirs). | **Every projection target.** |
-| **Runtime hooks** | On hosts exposing a tool lifecycle (`PreToolUse`/`PostToolUse`/`Stop`), a guard can deterministically block a call (e.g. `block_no_verify`). | **Hook-capable hosts only** (~2 of the supported set). |
-
-Full per-host breakdown: [`enforcement-by-host.md`](enforcement-by-host.md).
-
-The point: a runtime-first competitor's strongest enforcement simply **does not
-exist** on a host that has no hook surface. The compile-time layer is there on
-*that same host* because it rides in the config the host already reads.
-
-## Governance in action — three concrete traces
-
-### 1. A safety-floor rule survives projection into a static host
-`commit-policy` (`tier: safety-floor`) is compiled into Cursor's `.cursorrules`
-and Copilot's `copilot-instructions.md`. The host has no hook to block a
-`git commit`, but the constraint is **in the instruction file the host loads at
-session start** — present by construction, not dependent on a runtime primitive
-the host lacks (a static host gives it no runtime attention guarantee, but a
-runtime-only system gives it nothing at all here). A runtime-only system contributes *nothing* on these hosts.
-
-### 2. Intent routing, not a 500-artefact dump
-A prompt does not load all 281 skills. `dist/router.json` (103 routed rules, intent →
-skill, keyword/phrase/path triggers) carries the right skill on intent. The
-governance value is *selection discipline* — the host gets the relevant rule
-set, not the whole catalogue as context ballast.
-
-### 3. The enforcement spectrum is explicit, not implied
-On Claude Code / Cline (MCP) the safety-floor constraints get **both** layers:
-compile-time instruction **and** a deterministic runtime block. On Cursor /
-Windsurf / Copilot / Gemini they get the compile-time layer alone. We state
-which host gets which — we never imply "deterministic everywhere".
-
-## What this is NOT (honesty boundary)
-
-- **Not "un-strippable".** A human can edit any projected file. The claim is
-  *present-by-construction on every host* — a host's runtime cannot selectively
-  ignore it the way it ignores an absent runtime hook.
-- **Not a measured behaviour-change claim.** A length-controlled A/B
-  (hardened-constraint blocks vs a length-matched placebo) measured **honest-null
-  at the discipline ceiling** — the cooperative rules already catch the test
-  traps, so *adding emphasis* changed nothing measurable. The moat is that
-  governance is **present and portable across hosts**, not that more governance
-  prose provably changes a model's behaviour.
-- **Not deterministic on static hosts.** Compile-time governance is
-  model-cooperative; only hook-capable hosts get a hard block.
-
-## Why it's hard to copy
-
-A runtime-first system would have to re-author its governance to live in
-config space and project into every host's native format — i.e. become a
-content+governance layer — to match the reach. That is a different architecture,
-not a feature bolt-on. Meanwhile this package adds runtime hooks as an opt-in
-*superset* where hosts allow it, without depending on them for the floor.
-
-## See also
-
-- [`enforcement-by-host.md`](enforcement-by-host.md) — per-host enforcement mechanism.
-- [`capability-matrix.md`](capability-matrix.md) — which artifact type projects to which host.

package/docs/governance.md

@@ -1,96 +0,0 @@
-# Governance — own, age, and contract the skill surface
-
-How the 227-skill surface is governed for a **single-maintainer** project, with
-forward-structure for a team. Scope + sequencing settled by AI-council
-(claude-sonnet-4-5 + gpt-4o, 2026-06-09): build what gives a solo maintainer
-real leverage now; defer team-shaped ceremony and Phase-3 discovery conclusions.
-
-## Single Source of Truth rule
-
-```
-A GOVERNANCE FIELD LIVES IN EXACTLY ONE ARTEFACT.
-DERIVED VALUES ARE DOCUMENTED, NOT STORED.
-```
-
-`docs/contracts/skill-family-map.yml` is the machine-readable **spine**. Any
-field it carries (`family`, `primary_use`, `activation_scope`) must **not** be
-duplicated in another doc — policies and tooling *reference* the spine. A value
-that can be computed from other data (e.g. dormancy from `git log`) is
-**documented as a derivation, never stored** — stored copies drift.
-
-## `skill-family-map.yml` — the spine
-
-Per skill, three **base** fields (Phase 2):
-
-| Field | Meaning | Source |
-|---|---|---|
-| `family` | one of the 19 navigation families | the [skill taxonomy](skills-taxonomy.md) (pack + name-pattern) |
-| `primary_use` | one-line "use when …" | the skill's frontmatter `description:` (first clause) |
-| `activation_scope` | which pack(s) gate the skill, or `core` (always available) | frontmatter `pack:` / `packs:`, per ADR-040 |
-
-**Reserved for Phase 3** (intentionally absent now): `overlaps_with`,
-`candidate_for_merge`, `candidate_for_lens`, `candidate_for_internal`. These are
-**conclusions of the Phase-3 consolidation scan**, not metadata about a skill —
-populating them in Phase 2 would pre-empt Phase 3's "discover, merge nothing"
-mandate and anchor the analysis to today's bias.
-
-**Regeneration (reproducible):** the spine is generated from `src/skills/*/SKILL.md`
-— `family` via the taxonomy's ordered name-pattern rules (see
-[`skills-taxonomy.md`](skills-taxonomy.md) § Derivation), `primary_use` from the
-first clause of each `description:`, `activation_scope` from the declared
-`pack:`/`packs:` (or `core`). Re-run that logic to refresh; counts track the
-[artefact census](artefact-census.md).
-
-## Skill lifecycle policy
-
-States: **active** · **dormant** · **sunset**. Slots beside the
-`persona-governance` rule as its skill-side sibling.
-
-- **Dormancy is commit-based, not review-date-based.** A solo maintainer does not
-  hand-maintain `last_reviewed:` timestamps (busywork that drifts). Dormancy
-  signal = **no commits touching a skill's files in 6 months**
-  (`git log --since='6 months ago' -- src/skills/<name>/`). Derivable — so it is
-  *not* stored in the spine (Single Source of Truth rule).
-- **Dormancy triggers review, never auto-deprecation.** A dormant skill is a
-  prompt to ask "still earning its slot?" — the maintainer decides active / sunset.
-- **Sunset** is explicit + recorded in the removing commit (cf. `persona-governance`):
-  name the successor or the reason; no tombstone files.
-- A `last_reviewed:` / human-review field is **deferred until a second maintainer**
-  exists (then human review, not commit activity, is the signal worth recording).
-
-## Deferred governance (council-decided, not dropped)
-
-| Item | Why deferred | Lands in |
-|---|---|---|
-| **Skill ownership map** (maintainer per family) | one maintainer → per-family ownership is ceremony with zero information | when a 2nd maintainer exists; `owner:` would then be a spine column, not a separate CODEOWNERS |
-| **`candidate_*` / `overlaps_with`** spine fields | discovery *conclusions*, not metadata | Phase 3 (consolidation scan) |
-| **Command `category:` lint — full 125-command categorization** | product-surface judgment; large | Phase 2b / 3 — see [`command-category-governance.md`](contracts/command-category-governance.md) |
-
-## Legacy-path freeze (`.agent-src.uncondensed/`)
-
-The pre-relocation source path `.agent-src.uncondensed/` is dead (ADR-051; source
-of truth is `src/`). Existing stale **prose** mentions in `src/` are fixed
-**opportunistically** — a large blind sweep was rejected by AI-council
-(2026-06-09): the literal is also the *detection subject* of the reference
-linters (rewriting it disables them), and historical ADRs are correct as written.
-
-What is enforced instead — the debt cannot **grow**:
-
-```
-NO NEW `.agent-src.uncondensed/` REFERENCE MAY BE ADDED UNDER src/.
-```
-
-`scripts/check_no_new_legacy_path.py` (CI, PR-scoped via `gh pr diff`) fails on any
-**added** line under `src/` containing the literal — except the three files where
-it is legitimate forever (`_lib/agent_src.py`'s `LEGACY_SRC`, and the two
-`check_*` reference detectors). Existing mentions migrate to `src/` when their
-file is touched for another reason. Historical ADRs (`docs/decisions/`) keep their
-mentions; `internal/` (glama) + `agents/roadmaps/{archive,skipped}` are out of scope.
-
-## See also
-
-- [`docs/contracts/skill-family-map.yml`](contracts/skill-family-map.yml) — the spine.
-- [`skills-taxonomy.md`](skills-taxonomy.md) — the family derivation.
-- [`artefact-census.md`](artefact-census.md) — the counted baseline.
-- [`command-category-governance.md`](contracts/command-category-governance.md) — the deferred command-category hand-off.
-- `persona-governance` rule — the persona-side sibling of the lifecycle policy.

package/docs/guides/cross-repo-linked-projects.md

@@ -1,93 +0,0 @@
-# Working across linked sibling projects
-
-When two repositories change together — an API and its frontend, a service and
-a shared library — a change in one can silently break the other. The agent can
-already read and write a sibling repo, but it won't **proactively consider** one
-unless it knows the sibling is relevant. This feature closes that gap: it
-detects the sibling your IDE already attached and, after a one-time opt-in,
-makes the agent flag cross-repo impact by default.
-
-> **Scope — passive awareness (Option A).** The agent gains *awareness*: it
-> warns about cross-repo impact on relevant changes and can read/edit the
-> sibling on demand. It does **not** bulk-load the sibling's files into context
-> (that would blow up token cost). See
-> [ADR-032](../decisions/ADR-032-linked-projects-scope.md). Unrelated to
-> [ADR-029](../decisions/ADR-029-multi-workspace-deferred.md) (package root
-> layout).
-
-## Auto-detection (Claude Code — verified)
-
-If you attach a sibling repo in your IDE, the agent detects it from on-disk
-config and prompts **once** to opt it in:
-
-- **PhpStorm / IntelliJ** — a sibling attached via `.idea/modules.xml` /
-  `.idea/vcs.xml` (e.g. `../galawork-web`).
-- **VS Code** — folders in a `*.code-workspace`.
-
-On the first turn (and on a new attachment) the agent asks per detected sibling:
-include / decline / always / never-ask. Your choice is stored **local-only** in
-`.agent-settings.local.yml` (in agents/settings/) (gitignored, per-machine — see below). A declined
-sibling is never prompted again.
-
-Once a sibling is in scope, the agent proactively checks it for impact when a
-change here may affect it (API contract, shared types) and warns you — without
-loading its files wholesale. Large siblings (a real frontend easily exceeds
-20 000 files) are flagged `large` and surfaced as awareness only, never skipped.
-
-## Manual setup (other agents / any editor)
-
-Auto-detection is verified for Claude Code only. For Cursor, Augment, Copilot,
-or any editor without IDE attachment, add the sibling by hand to
-`.agent-settings.local.yml` (in agents/settings/):
-
-~~~yaml
-linked_projects:
-  - path: /abs/path/to/web   # or a path relative to the project
-    include: true
-~~~
-
-Or, if your agent reads a rules file, drop a short note there:
-
-~~~markdown
-## Linked sibling project: ../web
-
-`../web` changes alongside this repo. When an API/contract or shared-type
-change here may affect it, check `../web` for impact and warn. Don't load its
-files wholesale; access specific files on demand.
-~~~
-
-## Keep it local, never committed
-
-`.agent-settings.local.yml` (in agents/settings/) is **gitignored on purpose** — sibling paths are
-per-developer and per-machine. The installer does **not** touch your
-`.gitignore` (decision D2 — you own your ignore file), so if your project does
-not already ignore it, add:
-
-~~~gitignore
-.agent-settings.local.yml
-~~~
-
-## Validate it works
-
-Ask the agent:
-
-> Read `package.json` (or `composer.json`) from the linked sibling and tell me the project name.
-
-If it reports the name, cross-repo access works. An out-of-root edit will prompt
-for confirmation, then succeed — that is expected (the agent's permission gate
-still applies).
-
-## Next: pull context from a sibling
-
-Detection makes the agent *aware* of a sibling. To have it **read** targeted
-context from one — a shared type, an API contract, a config — without copying
-the sibling's files in, see [Cross-repo retrieval](cross-repo-retrieval.md)
-(`agent-config linked-projects:list` + `/knowledge:cross-repo`).
-
-## Tell us what works
-
-Auto-detection is verified for Claude Code only. If you use Cursor, Augment, or
-Copilot, please report whether the rule note alone worked, you needed to add the
-folder to the IDE workspace, or neither — that evidence is the trigger to extend
-verified auto-detection to your agent. See
-[ADR-032](../decisions/ADR-032-linked-projects-scope.md).

package/docs/guides/cross-repo-retrieval.md

@@ -1,61 +0,0 @@
-# Cross-repo retrieval — pull sibling context without copying files
-
-Once the agent knows about a sibling repo ([detection guide](cross-repo-linked-projects.md)),
-cross-repo retrieval lets it **read targeted context** from that sibling — a shared type, an
-API contract the frontend consumes, a config the sibling owns — without bulk-including the
-sibling's files. It is the read layer on top of detection.
-
-It stays inside [ADR-032](../decisions/ADR-032-linked-projects-scope.md) Option A: read-only,
-opt-in per sibling, targeted query only. No full-tree sweep, no implicit inclusion, no writes.
-
-## 1. See which siblings are reachable
-
-```
-agent-config linked-projects:list
-```
-
-Prints the opted-in siblings as `path · detected via · large`. Add `--all` to see detected
-siblings you have not decided on yet. A sibling only becomes reachable once you set
-`include: true` for it in `agents/settings/.agent-settings.local.yml` (see the detection guide).
-
-## 2. Retrieve targeted context
-
-```
-/knowledge:cross-repo "OrderApiContract"
-```
-
-Under the hood:
-
-```bash
-./scripts-run src/scripts/cross_repo_retrieve "OrderApiContract" [--path-scope 'src/*.ts'] [--max-chunks 8]
-```
-
-You get a bounded table — `source_repo · path · freshness · why` — drawn only from opted-in
-siblings. Each chunk is redacted (secrets and PII are scrubbed before anything is shown), so
-no credential ever crosses a repo boundary.
-
-## 3. Scope large siblings
-
-A sibling flagged `large` by the detector **requires** a `--path-scope` glob:
-
-```
-/knowledge:cross-repo "config" --path-scope 'packages/shared/**'
-```
-
-Without a scope, a large sibling is skipped with a note — this keeps retrieval cheap and
-targeted instead of walking a huge tree.
-
-## How it ranks in memory
-
-When a skill retrieves memory with the `cross-repo` type, matches are tagged `source: cross-repo`
-and scored **below** the project's own curated knowledge — so cross-repo context informs the
-answer but never outranks your own repo's truth.
-
-## Notes
-
-- **Read-only.** The surface never writes to a sibling. Out-of-root writes still pass the host
-  permission gate; cross-repo retrieval writes nothing.
-- **Opt-in only.** A sibling that is not `include: true` is never read.
-- **Targeted only.** Path-glob + content grep, never a blind full walk.
-- Contract: [`cross-repo-retrieval`](../contracts/cross-repo-retrieval.md). Detection story:
-  [`cross-repo-linked-projects`](cross-repo-linked-projects.md).