afriend 0.6.1__tar.gz

afriend-0.6.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tim
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

afriend-0.6.1/PKG-INFO

@@ -0,0 +1,579 @@
+Metadata-Version: 2.4
+Name: afriend
+Version: 0.6.1
+Summary: Cross-examine specs, plans, and reviews using other agent CLIs as adversarial reviewers
+Author: Tim
+License-Expression: MIT
+Project-URL: Repository, https://github.com/livingstaccato/afriend
+Project-URL: Issues, https://github.com/livingstaccato/afriend/issues
+Keywords: claude,codex,agent,code-review,cli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+![afriend](https://raw.githubusercontent.com/livingstaccato/afriend/main/docs/images/brand/afriend-banner.png)
+
+# afriend
+
+> Hand your spec, plan, or review to agent CLIs — `claude`, `codex`,
+> Antigravity (`agy`),
+> `opencode` — under adversarial lenses, then merge their critiques into one
+> ranked findings report.
+
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](pyproject.toml)
+[![Dependencies](https://img.shields.io/badge/runtime%20deps-none-brightgreen)](pyproject.toml)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![Tests](https://img.shields.io/badge/tests-2198-brightgreen)](tests/)
+
+It automates a workflow you may already do by hand: run a review, paste the
+findings into a different model, ask whether they hold up, carry the argument
+back. Doing that manually means holding a claim ledger in your head. This
+keeps the ledger on disk.
+
+---
+
+## 📋 Contents
+
+- [Why more than one model](#-why-more-than-one-model)
+- [Install](#-install)
+- [Quickstart](#-quickstart)
+- [How it works](#-how-it-works)
+- [Lenses](#-lenses)
+- [What you get back](#-what-you-get-back)
+- [What's implemented](#-whats-implemented)
+- [Documentation](#-documentation)
+- [Development](#-development)
+
+---
+
+## 🎯 Why more than one model
+
+A single reviewer produces confident prose. Several reviewers produce claims
+that **can be compared** — and the disagreements are where the real problems
+are.
+
+This tool's own design spec was built exactly this way:
+
+| Reviewer | Result |
+|---|---|
+| `codex` | 17 findings |
+| `claude` | 15 findings, plus one marked `unproven` — *"lens leaks attribution"* |
+| Antigravity (`agy`) | independently reproduced two of `claude`'s findings, **and** caught a shared-worktree race neither of the other two flagged |
+
+That `unproven` claim was later confirmed and fixed. No single reviewer's pass
+would have surfaced all of it — see the [revision history in the design
+spec](docs/superpowers/specs/2026-08-22-adversarial-friends-design.md#19-revision-history)
+for the full account.
+
+---
+
+## 📦 Install
+
+Requires **Python 3.11+** and at least one agent CLI. Judging modes additionally
+require two independent non-host friends. The runner itself is **stdlib-only**
+— zero runtime dependencies.
+
+```bash
+uv tool install afriend
+```
+
+`afriend` is the canonical distribution. `adversarial-friends` and `afriends`
+are compatibility/reservation distributions that install the matching
+`afriend` release; they add no alternate import or command.
+
+<details>
+<summary>Other install methods</summary>
+
+```bash
+# From git, for a version that is not yet released
+uv tool install git+https://github.com/livingstaccato/afriend
+
+# From a local checkout
+git clone https://github.com/livingstaccato/afriend
+cd afriend
+uv tool install .
+
+# Without installing at all
+python -m afriend doctor
+```
+
+</details>
+
+Then confirm what's actually available:
+
+```bash
+afriend doctor
+```
+
+`doctor` reports shared readiness — including `ready`,
+`reachable-unconfigured`, `unavailable`, `disabled`, `host-excluded`, and
+`policy-blocked` — plus what each friend can genuinely enforce. For Ollama,
+reachability alone is insufficient because dispatch also requires a model.
+
+---
+
+## 🚀 Quickstart
+
+In an agent host, select `/afriend` to route an explicit afriend
+request, or select `$afriend:afriend` directly. It hands review,
+status, setup/configuration, and resolution requests to focused skills:
+`review`, `status`, `configure`, and `resolve`.
+
+Conversational phrases such as `afriend review` and `afriend status` are
+routing language, not executable aliases: the stable CLI commands remain
+`afriend run`, `afriend status`, and `afriend doctor`.
+`afriend resume <run-id>` similarly routes to `afriend run --resume <run-id>`;
+it is not a claim resolution and needs no disposition or evidence.
+
+```bash
+afriend run docs/my-design.md
+```
+
+On the first review request in a host task, `/afriend` presents one compact
+preflight before dispatch:
+
+> About to start afriend to review `<artifact>` in `<mode>` mode
+> with `<profile>`. Scope: `<repository snapshot|document only>`. Friends:
+> `<name, provider, lens, role>`; external tools: `<denied|explicit grant>`.
+
+You can accept it, choose a task-only profile or mode, change the task-only
+roster, or stop. It is shown again only before a requested new loop iteration.
+The preflight describes authority; it never grants external tools, provider
+enablement, unsafe arguments, or sandbox exceptions. Direct CLI runs stay
+non-interactive.
+
+The built-in profiles are `quick` (one `report` fan-out), `balanced`
+(`crossexam`), and `thorough` (`loop`). `quick` is the default. Use
+`--profile NAME` for one run; an explicit `--mode` wins over the profile's
+mode and other explicit safe run flags win over profile values.
+
+The host is the orchestrator. In Codex, Codex remains the orchestrator and is
+included as a friend by default. The report labels it
+`host-self-review (advisory)`, `independent=false`: it contributes findings
+and advisory verdicts, but cannot satisfy two-independent-friend admission,
+`--require-friends` participation, judging quorum, gate clearance, or loop
+convergence. Judging modes need two independent non-host friends in addition
+to any host; a `report` can be host-only. Non-Codex hosts are excluded by
+default. `--include-self` and `--exclude-self` are mutually exclusive
+overrides.
+
+Manage persistent user defaults, including a default Ollama model, with:
+
+```bash
+afriend providers list
+afriend providers enable claude
+afriend providers disable opencode
+afriend providers set-model ollama qwen3:8b
+afriend providers clear-model ollama
+```
+
+Set up those defaults with an inspectable no-write preview, then apply only
+the exact choices you name:
+
+```bash
+afriend init --guided
+afriend init --guided --default-profile balanced --enable-provider claude
+afriend init --guided --apply --default-profile balanced --enable-provider claude
+```
+
+Guided setup reports discovered providers, the Codex advisory-host role when
+applicable, built-in profiles, and that external tools remain denied. Plain
+`afriend init` remains the direct roster-generation command.
+
+Manage named user profiles separately:
+
+```bash
+afriend profiles list
+afriend profiles create focused --base quick --timeout 300
+afriend profiles set-default focused
+```
+
+Profiles can carry only review-safe mode, preset, lenses, friend/timeout
+ceilings, and round/iteration ceilings. They cannot select providers, a
+friend roster, models, credentials, forwarded environment, external tools,
+unsafe arguments, or sandbox exceptions.
+
+For one automatic roster, `--enable-provider NAME` and
+`--disable-provider NAME` override those defaults. Disabled providers are not
+probed. An explicit `--friend` roster remains authoritative and may name the
+host or a disabled provider.
+
+External-tool authority is separate from provider selection. The repeatable
+required-value form is `--allow-external-tools=PROVIDER`; the explicit global
+grant is `--allow-external-tools=*`. Unknown, duplicate, or mixed `*` plus
+provider grants are invalid, and the old valueless form is invalid.
+`--unsafe-extra-args` requires the global `*` grant plus
+`--i-accept-unsandboxed`. Grants do not change provider defaults and must be
+repeated as the same normalized set on resume.
+
+**Stdout** carries one thing — the run directory. Read `report.md` inside it:
+
+```bash
+cat "$(afriend run docs/my-design.md --mode report)/report.md"
+```
+
+Pick your reviewers and lenses explicitly:
+
+```bash
+afriend run spec.md --friend codex:security --friend claude:ops
+```
+
+A third slot picks the model — required for `ollama`, which has no default:
+
+```bash
+afriend run spec.md --friend ollama:security:qwen3:0.6b
+```
+
+> ⚠️ `--friend` **replaces** discovery rather than adding to it. One
+> `--friend` flag means a one-friend roster. A `report` with one friend is
+> allowed as a recorded downgrade in `run.json` and `report.md` rather than
+> being presented as a full review. `crossexam`, `gate`, and `loop` require at
+> least two independent non-host friends; with fewer, they refuse with exit 3
+> before a run directory is created.
+
+Runtime depends on the slowest selected friend, document size, and mode.
+Progress goes to **stderr**: a line per friend as it finishes, and a heartbeat
+naming whatever is still outstanding, so a quiet run is distinguishable from
+a hung one. `--no-progress` silences it for a caller that captures both
+streams together; reducing `--timeout` turns slow friends into failures rather
+than making them faster.
+
+Each run also appends safe lifecycle records to `events.jsonl`: `run_started`,
+friend completion/failure, round completion, and `run_finished`. Records carry
+only identity, mode/profile, scope, status, round, duration, and next action;
+they never copy prompts, raw outputs, diagnostics, credentials, environment,
+or authority grants. After the run, inspect it without dispatching anything:
+
+```bash
+afriend status <run-id-or-path>
+afriend status <run-id-or-path> --watch
+afriend status <run-id-or-path> --json
+```
+
+`--watch` prints only new lifecycle events until the terminal event and treats
+an unterminated final event line as still being written. Runs without an event
+stream remain inspectable from `run.json`, `claims.jsonl`, and `report.md`.
+
+---
+
+## ⚙️ How it works
+
+![module architecture](https://raw.githubusercontent.com/livingstaccato/afriend/main/docs/architecture/components.png)
+
+Every friend gets its **own** prompt built from its **own** lens, runs in its
+**own** isolated directory, in its **own** process group:
+
+| Stage | What happens |
+|---|---|
+| 🔍 **Resolve** | Discover agent CLIs on `PATH`, round-robin a lens to each |
+| ✍️ **Prompt** | Build a per-friend prompt: shared contract header + that friend's lens prose + the artifact |
+| 🔒 **Isolate** | Each friend's effective scope selects its isolation directory: repo scope gets a private `git worktree` from one shared snapshot, while doc scope gets an artifact-only directory. Adapter read-only flags and, where required, OS confinement (`sandbox-exec` / `bwrap`) are then applied separately as a second line of defense — or the friend is refused |
+| 🛂 **Deny remote authority** | External tools are denied by default. An adapter that cannot neutralize provider-managed tools, plugins, apps, or MCP servers is `policy-blocked` unless `--allow-external-tools=PROVIDER` explicitly opts that provider in for this run |
+| 🧰 **Stage harnesses** | Adapter-owned workspace assets are copied into each isolated run workspace. Antigravity receives the controlled `afriend-reviewer` agent selected with `--agent`, `--disable-slash-commands`, `--mode plan`, and `--sandbox` |
+| ⚡ **Dispatch** | Parallel, one thread per friend, each in its own process group with a kill deadline of `--timeout + 60s` |
+| 🧩 **Normalize** | Unwrap the CLI's own JSON envelope, strip ANSI, recover the payload, validate against the claim schema |
+| 🔗 **Merge** | Exact-merge identical claims into aliases — accumulating origins so corroboration survives |
+| 📄 **Report** | Rank findings, render `report.md`, write the append-only ledger |
+
+The snapshot includes **untracked** files (`git stash create` omits them), and
+the working tree is never touched — a friend reviewing your repo can't see a
+half-staged index or scribble on your checkout.
+
+There are two supported ways to select review context:
+
+```bash
+afriend run docs/plan.md --mode report
+afriend run /tmp/reviews/plan.md --repo "$PWD" --mode report
+```
+
+The first form selects scope automatically only when the artifact's resolved
+final target is inside the invocation repository: it receives a repository
+snapshot. An in-repository symlink whose target resolves outside that
+repository is doc scope only, and no repository snapshot is minted; a path
+outside a Git repository likewise produces a visible doc-scope warning on
+stderr before friends start. The second form selects the named repository
+explicitly; `--repo` must name that repository's Git worktree root. It is the
+deliberate route for an independently frozen external artifact together
+with selected repository code. It does not grant new provider, external-tool,
+or write authority. Normal untracked, non-ignored files are included in an
+automatic snapshot.
+
+Gitignored artifacts are intentionally excluded from automatic Git-blob
+binding and fail rather than falling back to a stale `HEAD` version. Use the
+explicit `--repo` form when an ignored or outside artifact needs the named
+repository's code context.
+
+On Linux, a confined friend uses `bwrap` with the required system paths
+read-only. If `/etc/resolv.conf` resolves to a safe regular file elsewhere on
+the host, the sandbox exposes that resolver target read-only too. DNS therefore
+continues to work without granting general access to the host filesystem.
+
+For a provider without a verified read-only/write-protection mode, make
+`sandbox-exec` (macOS) or `bwrap` (Linux) available, or choose a provider
+with a verified read-only/write-protection mode. That mode controls writes,
+not filesystem reads, and does not replace OS read confinement. A provider
+with a verified read-only/write-protection mode does not need
+`--allow-unsandboxed-friend`. That flag is explicit risk acceptance, not a
+normal fix: the affected provider runs without OS confinement and retains
+same-user filesystem read access.
+
+<details>
+<summary>Full run flow, step by step</summary>
+
+![run flow](https://raw.githubusercontent.com/livingstaccato/afriend/main/docs/architecture/run-flow.png)
+
+</details>
+
+### Corroboration is the point
+
+Two friends independently reaching the same conclusion is the strongest signal
+this tool produces, so deduplication is built to never destroy it:
+
+![claim lifecycle](https://raw.githubusercontent.com/livingstaccato/afriend/main/docs/architecture/claim-lifecycle.png)
+
+Dedup is **deliberately** exact-match — whitespace and case only. Two friends
+describing one defect in different words produce two claims, which costs a
+round. Guessing at equivalence would corrupt the ledger, which is worse.
+
+### Claim states in cross-examination
+
+Every claim `--mode crossexam` produces ends in one of eight states. Two of
+them — `deadlocked` and `settled-upheld` — deliberately need a human, and the
+report says so rather than quietly resolving them.
+
+![crossexam states](https://raw.githubusercontent.com/livingstaccato/afriend/main/docs/architecture/crossexam-states.png)
+
+### The gate loop
+
+`--mode gate` is the one that fails a build, and clearing it is a
+back-and-forth rather than a single command:
+
+![gate workflow](https://raw.githubusercontent.com/livingstaccato/afriend/main/docs/architecture/gate-workflow.png)
+
+---
+
+## 🔬 Lenses
+
+A lens is prose, not a config string. Its text is injected into that friend's
+prompt, so it shapes what the friend actually looks for.
+
+| Lens | Default scope | Requires a failure scenario |
+|---|---|---|
+| `assumptions` | doc | ✅ |
+| `security` | repo | ✅ |
+| `ops` | repo | ✅ |
+| `testability` | repo | ✅ |
+| `spec-vs-reality` | repo | ✅ |
+| `scope` | doc | ❌ — advisory only |
+
+`scope` is the one lens that doesn't demand a concrete failure scenario;
+"this is more than you need" is a legitimate finding without one. Claims from
+it are marked *(advisory)* in the report so they never carry the same weight
+as a reproducible defect.
+
+---
+
+## 📂 What you get back
+
+```
+<run-dir>/
+├── report.md          ← ranked findings, corroboration, downgrades
+├── run.json           ← machine-readable: friends, statuses, downgrades
+├── events.jsonl       ← append-only safe lifecycle events
+├── claims.jsonl       ← append-only ledger: claims, aliases
+├── artifact/          ← frozen copy of what was reviewed, hashed
+└── round-1/
+    ├── <friend>.prompt ← exactly what this friend was asked
+    ├── <friend>.raw    ← its unmodified stdout
+    ├── <friend>.err    ← its stderr (always present, even when empty)
+    ├── <friend>.meta   ← argv, exit code, duration, timeout, orphan status
+    └── <friend>.sandbox ← the OS policy it ran under, when one was applied
+```
+
+Runs land under `${XDG_STATE_HOME:-~/.local/state}/afriend/runs/`,
+or wherever `--out` points.
+
+Everything a friend was asked and everything it said is on disk. When a run
+comes back thin, that's what you read — not a guess.
+
+---
+
+## ✅ What's implemented
+
+**All four modes run.**
+
+| Mode | What it does |
+|---|---|
+| `report` | The default: one critique fan-out. Every friend critiques in parallel; claims merge into one ranked report. |
+| `crossexam` | Then friends judge the claims they did not write, blind, for three total rounds by default or until each settles or deadlocks. |
+| `gate` | Then every non-advisory claim that did not clear needs an explicit resolution — this is the one that fails a build. |
+| `loop` | Repeats for a maximum of five iterations by default, until two consecutive dry rounds surface nothing new. |
+
+```bash
+afriend run docs/design.md --mode crossexam
+afriend run docs/design.md --mode gate       # exit 1 while anything blocks
+afriend resolve <run-id> --list
+afriend resolve <run-id> --next
+afriend resolve <run-id> --claim c-0001@1 \
+    --disposition fixed --evidence src/auth.py:38
+```
+
+Disagreement is the output rather than a problem: two judges who still
+disagree at `--max-rounds` leave the claim `deadlocked`, and the report
+quotes both sides verbatim instead of resolving it by majority.
+
+A resolution is an **attestation**, and the tool says so. It cannot know a
+defect is gone — only whether the location you named actually changed since
+the run started. A fix that landed outside the reviewed artifact is fine.
+`--disposition fixed` requires a verifiably changed location; unchanged or
+unverifiable evidence is refused. Use `accepted-risk` when verification is
+intentionally unavailable.
+
+Deduplication is judgment the runner declines to fake. `--merge exact`
+(the default) merges only identical claims and always finishes unaided;
+`--merge orchestrator` stops with exit `10`, writes the claims to
+`REQUEST.json`, and waits for you to say which are duplicates:
+
+```bash
+afriend run docs/design.md --merge orchestrator   # exit 10, writes REQUEST.json
+# ...fill in the merges, save as RESPONSE.json...
+afriend run --resume <run-id>                     # round 1 is not re-run
+```
+
+Resume verifies the original frozen artifact hash and saved Git snapshot
+before dispatch; it never substitutes current files. It uses the saved
+repository scope and rejects `--repo`, so a resume cannot replace the original
+automatic or explicit selection. Security grants are
+also never restored from `run.json`: options such as
+`--allow-external-tools=PROVIDER` grants (or the global `=*` grant) must be
+repeated as the same normalized set.
+
+Tired of `--friend` flags? `afriend init` writes a roster from what is
+actually installed, and `~/.config/afriend/roster.toml` is picked
+up automatically. A repo-local roster never is — a cloned repo does not get
+to choose who reviews it (§13).
+
+The same halt serves unparseable output (§14.2): repair is a pure
+transformation with no model call, so when it fails the runner asks you to
+read the raw text rather than discarding whatever the friend found.
+
+**There is no `--max-spend-usd`.** A dollar cap needs per-CLI cost reporting
+nobody has captured, and a flag that silently never fires is worse than none
+— you would set it and believe you were protected. Use `--max-calls`, which
+is derived from your roster and actually enforced.
+
+| Friend | Status |
+|---|---|
+| `claude` | ✅ ships |
+| `codex` | ✅ ships |
+| `agy` | ✅ ships |
+| `opencode` | ✅ ships — no read-only mode, reported honestly |
+| `ollama` | ✅ ships — local models over HTTP, no schema/read-only to enforce; needs an explicit model |
+
+Antigravity's controlled reviewer is staged into the run's isolated workspace;
+it does not edit global Antigravity configuration. The staged agent and
+`--sandbox` are defense in depth, but sandbox does not mean external tools
+were denied. Antigravity remains `external_tools=uncontrolled` because its
+CLI cannot prove every plugin/MCP integration disabled invocation-locally.
+That is an accepted
+best-effort limitation: Antigravity is policy-blocked by default, while
+`--allow-external-tools=agy` records it as `explicitly-allowed`.
+
+Antigravity is the shipped Google harness, identified as `agy` in CLI and
+provider configuration.
+
+### Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | the run reached terminal states with nothing blocked |
+| `1` | a `gate` still has claims needing a resolution, or every dispatched friend failed |
+| `2` | usage error — bad flag, unknown CLI, missing artifact |
+| `3` | no usable friends found, or a judging mode resolved fewer than two independent non-host friends; refused before a run directory |
+| `10` | `--merge orchestrator` is waiting for you to adjudicate merges |
+| `11` | a ceiling was hit — including natural `--max-loop-iterations` exhaustion without convergence; the run was truncated, not decided |
+| `12` | `--require-friends N` was set and fewer than `N` friends answered |
+| `128+N` | aborted by signal N — isolation torn down, friends killed |
+
+A ceiling outranks everything below it, so a CI wrapper can read `11` as
+"retry" and `1` as "block" without ambiguity.
+
+---
+
+## 📚 Documentation
+
+| Where | What |
+|---|---|
+| [docs/](docs/README.md) | Documentation index |
+| [/afriend router](src/afriend/assets/entrypoints/afriend/SKILL.md) | Explicit product router and review workflow |
+| [review](src/afriend/assets/entrypoints/review/SKILL.md) | Start and interpret a review run |
+| [status](src/afriend/assets/entrypoints/status/SKILL.md) | Read-only provider and named-run status |
+| [configure](src/afriend/assets/entrypoints/configure/SKILL.md) | Explicit provider-default changes |
+| [resolve](src/afriend/assets/entrypoints/resolve/SKILL.md) | Named-run claim resolutions |
+| [modes](src/afriend/assets/entrypoints/afriend/references/modes.md) | `report`, `crossexam`, `gate`, and `loop` |
+| [architecture/](docs/architecture/README.md) | Diagrams and their sources |
+| [design spec](docs/superpowers/specs/2026-08-22-adversarial-friends-design.md) | The full design, including the adversarial review that produced it |
+
+### Using it as a skill or plugin
+
+The skill payload ships **inside the wheel** as package data, and is mirrored
+under [`plugins/`](plugins/) for loaders that can't install a Python package:
+
+```bash
+# Claude Code
+/plugin marketplace add /path/to/afriend/plugins
+```
+
+Plugins package capabilities; the afriend plugin provides exactly
+five skills: `/afriend`, `review`, `status`, `configure`, and `resolve`.
+`/afriend` is the only router and short slash selector; direct qualified
+selection is `$afriend:afriend`. The CLI never runs automatically
+by itself. Generic “review this,” “poke holes,” “second opinion,” and
+architectural decision requests stay ordinary Codex work.
+
+The package must therefore be installed for the skill to work — `afriend
+doctor` is the check. Conversational forms route to stable commands; they are
+not executable aliases.
+
+---
+
+## 🛠 Development
+
+```bash
+make install    # uv sync
+make test       # pytest
+make quality    # every portable CI gate, wheel checks, and tests
+make diagrams   # re-render docs/architecture/*.puml
+```
+
+`make quality` runs every portable CI gate, including wheel construction and
+isolated installation. Linux CI additionally installs bubblewrap and requires
+the real OS-confinement tests to execute; macOS cannot reproduce that Linux-
+specific assertion locally. Use `make act-ci` for the closest local Linux run.
+
+Two gates catch drift that is otherwise silent:
+
+- **`plugin-sync`** — `src/afriend/assets/` is canonical; its
+  entrypoints project directly to plugin skills and runtime assets project
+  beneath `skills/afriend/`. Edit assets, then `make plugin-sync-copy`.
+- **`version-sync`** — `VERSION` must match the `version` field in every
+  plugin manifest.
+
+See [AGENTS.md](AGENTS.md) for repository layout and conventions.
+
+---
+
+## 📄 License
+
+MIT — see [LICENSE](LICENSE).