microphone-cli 0.8.0__tar.gz → 0.8.2__tar.gz

{microphone_cli-0.8.0 → microphone_cli-0.8.2}/CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to this project will be documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/). This project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.8.2] - 2026-09-06
+
+### Fixed
+
+- **Documented `markdownlint-cli2` as though `uv sync` installed it** (Qodo review, PR #2) — it is an npm tool absent from the dev dependency group, so a fresh checkout following `CLAUDE.md` hit command-not-found. Both `CLAUDE.md` and `README.md` now show the `npm install -g markdownlint-cli2@0.21.0` step, pinned to the version CI installs.
+- **Overstated what CI's `version-check` job enforces** (Qodo review, PR #2) — the workflow compares the PR version against `main` as strings and fails only on equality, so a downgrade passes. The docs now describe it as a forgotten-bump tripwire rather than a guarantee the version moved forward.
+
+## [0.8.1] - 2026-09-06
+
+### Changed
+
+- **`CLAUDE.md` re-initialized from the seed placeholder into a full runtime prompt** — records the repo's actual state (renamed template scaffold, no microphone domain code yet, and the specific files still carrying template prose), the build/test/lint/rubric-gate command set, the CLI architecture (the `register(sub)` dispatch pattern, the `CliError` / stream-split / `--json` contracts the rubric enforces, and the `parser_class` propagation nested nouns need), the checklist for adding a verb or noun, and the CI/release and vendored-skill conventions.
+- **`README.md` corrected and refreshed** — the quickstart told readers to run `microphone-cli`, which does not exist: `pyproject.toml` declares the console script as `microphone`, so `uv run microphone-cli whoami` failed with `Failed to spawn`. Commands now use `microphone`, with a note that argparse still prints `microphone-cli` as the program name. Also adds a scaffold-status banner, drops the stale skill count (said 11; there are 19 vendored directories), fixes the backend description to name this agent rather than the template, and replaces the template-only rename section with a Development section.
+
+### Fixed
+
+- **`CLAUDE.md` claimed `culture.yaml` declares `backend: claude`** — it declares `colleague`, which is why `AGENTS.colleague.md` is the resident prompt file `doctor` checks for. The new file records the correct backend-to-prompt-file mapping.
+
 ## [0.8.0] - 2026-09-05
 
 ### Added

microphone_cli-0.8.2/CLAUDE.md

@@ -0,0 +1,169 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this repo is
+
+**microphone-cli** — an agent-first CLI for USB microphones and microphone
+arrays: enumerate devices, select and inspect channels, control gain and sample
+format, and read direction-of-arrival from array firmware.
+
+**Current state: scaffold only.** The repo was cloned from the AgentCulture
+agent template (`5f9b1bd scaffold microphone-cli from culture-agent-template`).
+The package is renamed and the CI/identity/skills baseline is live, but **no
+microphone domain code exists yet** — the only verbs are the template's
+agent-first introspection surface (`whoami`, `learn`, `explain`, `overview`,
+`doctor`, `cli overview`). Several strings still describe the template
+("a clonable template for AgentCulture mesh agents") rather than the microphone
+domain: `microphone_cli/cli/_commands/learn.py`, `overview.py` (`_ARTIFACTS`),
+`microphone_cli/explain/catalog.py`, and `README.md`. Rewrite those as the
+domain lands.
+
+## Commands
+
+```bash
+uv sync                                   # install (dev group included)
+
+uv run pytest -n auto                     # full suite, parallel
+uv run pytest tests/test_cli.py           # one file
+uv run pytest -k whoami                   # one test / pattern
+uv run pytest --cov=microphone_cli --cov-report=term   # coverage (fail_under=60)
+
+uv run black --check microphone_cli tests # CI lint set — all four must pass
+uv run isort --check-only microphone_cli tests
+uv run flake8 microphone_cli tests
+uv run bandit -c pyproject.toml -r microphone_cli
+
+uv run teken cli doctor . --strict        # the agent-first rubric gate CI runs
+
+uv run microphone whoami                  # the installed console script
+uv run microphone doctor --json
+python -m microphone_cli learn
+```
+
+**Markdown lint is not a `uv` tool** — `uv sync` does not install it, so it is
+not available on a fresh checkout. CI installs it from npm; do the same locally,
+pinning the version CI uses so results match:
+
+```bash
+npm install -g markdownlint-cli2@0.21.0
+markdownlint-cli2 "**/*.md" "#node_modules" "#.local" "#.claude/skills"
+```
+
+Config lives in `.markdownlint-cli2.yaml` (MD013 and MD060 off, MD024
+siblings-only for the changelog; `.claude/skills/**` ignored).
+
+### Console-script name
+
+`pyproject.toml` declares `microphone = "microphone_cli.cli:main"` — the binary
+is **`microphone`**, not `microphone-cli`. The argparse `prog` is
+`"microphone-cli"`, so `--help` and every doc string say `microphone-cli …`
+while the actual command is `microphone …`. Either rename the script or the
+`prog` before this ships; until then, prefer `microphone` in anything runnable.
+
+## Architecture
+
+Zero runtime dependencies (`dependencies = []` in `pyproject.toml`) — that is a
+deliberate constraint of the agent-first template, and `culture.yaml` is parsed
+by hand in `whoami.py` rather than pulling in PyYAML. Keep new runtime deps out
+unless the microphone backend genuinely requires one.
+
+### CLI dispatch
+
+`microphone_cli/cli/__init__.py` is the only place that knows the verb set.
+`_build_parser()` imports each command module and calls its `register(sub)`;
+`main()` parses and hands off to `_dispatch()`, which invokes `args.func(args)`.
+
+Three contracts hold across the whole surface, and the rubric gate checks them:
+
+- **Errors** — `microphone_cli/cli/_errors.py`. Every failure raises `CliError`
+  (`{code, message, remediation}`). `_dispatch` wraps any stray exception into
+  one, so **no traceback ever reaches stderr**. Exit codes: `0` success,
+  `1` user error, `2` environment error, `3+` reserved.
+- **Streams** — `microphone_cli/cli/_output.py`. Results to stdout
+  (`emit_result`), errors and diagnostics to stderr (`emit_error`,
+  `emit_diagnostic`); they never mix. Text errors render `error:` + `hint:`.
+- **`--json` everywhere** — every parser adds `--json`; handlers read it via
+  `getattr(args, "json", False)`.
+
+Argparse's own errors also honour these contracts: `_CliArgumentParser`
+overrides `.error()` to emit a `CliError`, and subparsers are built with
+`parser_class=_CliArgumentParser` so nested nouns inherit it. Because
+parse-time errors happen before `args.json` exists, `main()` pre-scans raw argv
+for `--json` into the class-level `_json_hint`. **When you add a nested
+subparser group, pass `parser_class=type(p)` through** (see
+`_commands/cli.py`) — forgetting it silently drops that group back to
+argparse's default `exit(2)` behaviour.
+
+### Identity
+
+`_commands/whoami.py` walks up from `__file__` (not the CWD) to find the repo's
+own `culture.yaml`, so identity is the agent's, not the caller's. In a wheel
+install no `culture.yaml` ships and the literal fallbacks apply. `doctor` and
+`overview` both build on `whoami`'s `report()` / `read_agent_fields()`.
+
+`doctor` mirrors the two `steward doctor` invariants — **prompt-file-present**
+and **backend-consistency** — via the `_PROMPT_FILE` map (`claude` →
+`CLAUDE.md`, `colleague` → `AGENTS.colleague.md`, `acp` → `AGENTS.md`,
+`gemini` → `GEMINI.md`), plus a skills-present check. It returns
+`{healthy, checks: [{id, passed, severity, message, remediation}]}` — the
+rubric depends on that exact shape.
+
+**This agent runs `backend: colleague`** (`culture.yaml`), so its resident
+prompt file is `AGENTS.colleague.md`; this `CLAUDE.md` is the Claude Code
+guidance file. Changing `backend` means adding the matching prompt file or
+`doctor` (and CI's rubric gate) goes red.
+
+### Adding a verb or noun
+
+1. New module in `microphone_cli/cli/_commands/` exposing `register(sub)`, with
+   `--json` and a `func` default.
+2. Register it in `_build_parser()` (there is a marked spot).
+3. **Add a catalog entry** in `microphone_cli/explain/catalog.py` keyed by the
+   command-path tuple — `tests/test_cli.py::test_every_catalog_path_resolves`
+   walks every key, and the rubric requires an `explain` entry per path.
+4. Update the command map in `_commands/learn.py` (both `_TEXT` and
+   `_as_json_payload()`) and the `_VERBS` list in `_commands/overview.py`.
+5. A noun group that gets action-verbs **must** also expose `<noun> overview` —
+   the rubric's `overview_cli_noun_exists` check. `_commands/cli.py` is the
+   worked example (its bare form prints its own overview).
+6. Descriptive verbs must not hard-fail on a bad target path — `overview`
+   accepts and ignores a positional `target` for exactly this reason.
+
+## CI and release
+
+Three jobs in `.github/workflows/tests.yml`: `test` (pytest + coverage →
+SonarCloud, scan skipped when `SONAR_TOKEN` is empty, so fork PRs stay green),
+`lint` (black, isort, flake8, bandit, markdownlint, `teken cli doctor --strict`),
+and `version-check`.
+
+**Every PR bumps the version — including docs-, config-, and CI-only PRs.**
+Use the `version-bump` skill (or edit `pyproject.toml` + `CHANGELOG.md` by hand,
+Keep-a-Changelog format). `__version__` is read from package metadata, so there
+is no second version literal to update.
+
+`version-check` only partly enforces that rule: it compares the PR's
+`pyproject.toml` version against `origin/main` as **strings** and fails on
+equality alone. Any different value passes, a downgrade included — `0.8.1` →
+`0.8.0` is green today. Treat the check as a "did you forget entirely?" tripwire,
+not a guarantee the version moved forward; the publish job is what actually
+breaks later. (The comparison is string-equality in every AgentCulture sibling,
+so tightening it belongs upstream, not in this repo alone.)
+
+`publish.yml` publishes to TestPyPI on same-repo PRs (`<version>.devN`) and to
+PyPI on push to main, both via Trusted Publishing.
+
+Line length is **100** (black, isort profile=black, flake8 with `E203,W503`
+ignored). SonarCloud project key: `agentculture_microphone-cli`; the quality
+gate blocks CI when the token is configured.
+
+## Vendored skills
+
+`.claude/skills/` is vendored **cite-don't-import** from `guildmaster` (several
+originate in `devague`, one in `colleague`). Do not hand-edit them — they are
+excluded from markdownlint and Sonar for that reason. Provenance and the
+re-sync procedure live in `docs/skill-sources.md`; per-machine paths go in a
+git-ignored `.claude/skills.local.yaml` (copy the `.example`).
+
+Use the `cicd` skill for PR creation and review-comment handling. Online posts
+made outside those scripts sign as `- microphone-cli (Claude)`.

{microphone_cli-0.8.0 → microphone_cli-0.8.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: microphone-cli
-Version: 0.8.0
+Version: 0.8.2
 Summary: Agent-first CLI for USB microphones and microphone arrays: enumerate devices, select and inspect channels, control gain and sample format, and read direction-of-arrival from array firmware.
 Project-URL: Homepage, https://github.com/agentculture/microphone-cli
 Project-URL: Issues, https://github.com/agentculture/microphone-cli/issues
@@ -17,17 +17,23 @@ Description-Content-Type: text/markdown
 
 # microphone-cli
 
-Agent-first CLI for USB microphones and microphone arrays: enumerate devices, select and inspect channels, control gain and sample format, and read direction-of-arrival from array firmware.
+Agent-first CLI for USB microphones and microphone arrays: enumerate devices,
+select and inspect channels, control gain and sample format, and read
+direction-of-arrival from array firmware.
+
+> **Status: scaffold.** The identity, CI, and agent-first CLI baseline are in
+> place; the microphone domain verbs are not implemented yet. What ships today
+> is the introspection surface below.
 
 ## What you get
 
 - **An agent-first CLI** cited from [teken](https://github.com/agentculture/teken)
   (`afi-cli`) — the runtime package has no third-party dependencies.
 - **A mesh identity** — `culture.yaml` (`suffix` + `backend`) and the matching
-  resident prompt file (`AGENTS.colleague.md`, since this template runs
+  resident prompt file (`AGENTS.colleague.md`, since this agent runs
   `backend: colleague`).
-- **The canonical guildmaster skill kit** (11 skills) under `.claude/skills/`,
-  vendored cite-don't-import. See [`docs/skill-sources.md`](docs/skill-sources.md).
+- **The canonical guildmaster skill kit** under `.claude/skills/`, vendored
+  cite-don't-import. See [`docs/skill-sources.md`](docs/skill-sources.md).
 - **A build + deploy baseline** — pytest, lint, the agent-first rubric gate, and
   PyPI Trusted Publishing wired into GitHub Actions.
 
@@ -36,11 +42,15 @@ Agent-first CLI for USB microphones and microphone arrays: enumerate devices, se
 ```bash
 uv sync
 uv run pytest -n auto                 # run the test suite
-uv run microphone-cli whoami  # identity from culture.yaml
-uv run microphone-cli learn   # self-teaching prompt (add --json)
+uv run microphone whoami              # identity from culture.yaml
+uv run microphone learn               # self-teaching prompt (add --json)
 uv run teken cli doctor . --strict    # the agent-first rubric gate CI runs
 ```
 
+The installed console script is **`microphone`**. Argparse still prints
+`microphone-cli` as the program name in `--help` output; the runnable command is
+`microphone`.
+
 ## CLI
 
 | Verb | What it does |
@@ -56,20 +66,32 @@ Every command supports `--json`. Results go to stdout, errors/diagnostics to
 stderr (never mixed). Exit codes: `0` success, `1` user error, `2` environment
 error, `3+` reserved.
 
-## Make it your own
+## Development
+
+```bash
+uv run pytest tests/test_cli.py       # a single file
+uv run pytest -k whoami               # a single test
+uv run black --check microphone_cli tests
+uv run isort --check-only microphone_cli tests
+uv run flake8 microphone_cli tests
+uv run bandit -c pyproject.toml -r microphone_cli
+```
 
-1. Rename the package `microphone_cli/` and the `microphone-cli`
-   CLI/dist name throughout `pyproject.toml`, the package, `tests/`,
-   `sonar-project.properties`, and this `README.md`. The name is hard-coded in
-   ~100 places, so list every occurrence first — see the `git grep` discovery
-   command in [`CLAUDE.md`](CLAUDE.md), the authoritative rename procedure.
-2. Edit `culture.yaml` with your `suffix` and `backend`.
-3. Rewrite `CLAUDE.md` for your agent and run `/init`.
-4. Re-vendor only the skills you need from guildmaster (see
-   [`docs/skill-sources.md`](docs/skill-sources.md)).
+Every PR bumps the version in `pyproject.toml` and adds a `CHANGELOG.md` entry,
+even for docs- and CI-only changes. CI's `version-check` job catches a forgotten
+bump by failing when the version still matches `main`; it does not verify the
+version moved *forward*.
+
+Markdown lint is an npm tool, not a `uv` one — install it separately, pinned to
+the version CI uses:
+
+```bash
+npm install -g markdownlint-cli2@0.21.0
+markdownlint-cli2 "**/*.md" "#node_modules" "#.local" "#.claude/skills"
+```
 
-See [`CLAUDE.md`](CLAUDE.md) for the full conventions (version-bump-every-PR,
-the `cicd` PR lane, deploy setup).
+See [`CLAUDE.md`](CLAUDE.md) for the architecture, the CLI contracts (errors,
+stream split, `--json`), and how to add a verb or noun group.
 
 ## License
 

microphone_cli-0.8.2/README.md

@@ -0,0 +1,81 @@
+# microphone-cli
+
+Agent-first CLI for USB microphones and microphone arrays: enumerate devices,
+select and inspect channels, control gain and sample format, and read
+direction-of-arrival from array firmware.
+
+> **Status: scaffold.** The identity, CI, and agent-first CLI baseline are in
+> place; the microphone domain verbs are not implemented yet. What ships today
+> is the introspection surface below.
+
+## What you get
+
+- **An agent-first CLI** cited from [teken](https://github.com/agentculture/teken)
+  (`afi-cli`) — the runtime package has no third-party dependencies.
+- **A mesh identity** — `culture.yaml` (`suffix` + `backend`) and the matching
+  resident prompt file (`AGENTS.colleague.md`, since this agent runs
+  `backend: colleague`).
+- **The canonical guildmaster skill kit** under `.claude/skills/`, vendored
+  cite-don't-import. See [`docs/skill-sources.md`](docs/skill-sources.md).
+- **A build + deploy baseline** — pytest, lint, the agent-first rubric gate, and
+  PyPI Trusted Publishing wired into GitHub Actions.
+
+## Quickstart
+
+```bash
+uv sync
+uv run pytest -n auto                 # run the test suite
+uv run microphone whoami              # identity from culture.yaml
+uv run microphone learn               # self-teaching prompt (add --json)
+uv run teken cli doctor . --strict    # the agent-first rubric gate CI runs
+```
+
+The installed console script is **`microphone`**. Argparse still prints
+`microphone-cli` as the program name in `--help` output; the runnable command is
+`microphone`.
+
+## CLI
+
+| Verb | What it does |
+|------|--------------|
+| `whoami` | Report this agent's nick, version, backend, and model from `culture.yaml`. |
+| `learn` | Print a structured self-teaching prompt. |
+| `explain <path>` | Markdown docs for any noun/verb path. |
+| `overview` | Read-only descriptive snapshot of the agent. |
+| `doctor` | Check the agent-identity invariants (prompt-file-present, backend-consistency). |
+| `cli overview` | Describe the CLI surface itself. |
+
+Every command supports `--json`. Results go to stdout, errors/diagnostics to
+stderr (never mixed). Exit codes: `0` success, `1` user error, `2` environment
+error, `3+` reserved.
+
+## Development
+
+```bash
+uv run pytest tests/test_cli.py       # a single file
+uv run pytest -k whoami               # a single test
+uv run black --check microphone_cli tests
+uv run isort --check-only microphone_cli tests
+uv run flake8 microphone_cli tests
+uv run bandit -c pyproject.toml -r microphone_cli
+```
+
+Every PR bumps the version in `pyproject.toml` and adds a `CHANGELOG.md` entry,
+even for docs- and CI-only changes. CI's `version-check` job catches a forgotten
+bump by failing when the version still matches `main`; it does not verify the
+version moved *forward*.
+
+Markdown lint is an npm tool, not a `uv` one — install it separately, pinned to
+the version CI uses:
+
+```bash
+npm install -g markdownlint-cli2@0.21.0
+markdownlint-cli2 "**/*.md" "#node_modules" "#.local" "#.claude/skills"
+```
+
+See [`CLAUDE.md`](CLAUDE.md) for the architecture, the CLI contracts (errors,
+stream split, `--json`), and how to add a verb or noun group.
+
+## License
+
+Apache 2.0 — see [`LICENSE`](LICENSE).

{microphone_cli-0.8.0 → microphone_cli-0.8.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "microphone-cli"
-version = "0.8.0"
+version = "0.8.2"
 description = "Agent-first CLI for USB microphones and microphone arrays: enumerate devices, select and inspect channels, control gain and sample format, and read direction-of-arrival from array firmware."
 readme = "README.md"
 license = "Apache-2.0"

{microphone_cli-0.8.0 → microphone_cli-0.8.2}/uv.lock

@@ -154,37 +154,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/61/e8/cb8e80d6f9f55b99588625062822bf946cf03ed06315df4bd8397f5632a1/coverage-7.14.0-py3-none-any.whl", hash = "sha256:8de5b61163aee3d05c8a2beab6f47913df7981dad1baf82c414d99158c286ab1", size = 211764, upload-time = "2026-05-10T18:02:29.538Z" },
 ]
 
-[[package]]
-name = "microphone-cli"
-version = "0.8.0"
-source = { editable = "." }
-
-[package.dev-dependencies]
-dev = [
-    { name = "bandit" },
-    { name = "black" },
-    { name = "flake8" },
-    { name = "isort" },
-    { name = "pytest" },
-    { name = "pytest-cov" },
-    { name = "pytest-xdist" },
-    { name = "teken" },
-]
-
-[package.metadata]
-
-[package.metadata.requires-dev]
-dev = [
-    { name = "bandit", specifier = ">=1.7.5" },
-    { name = "black", specifier = ">=23.7.0" },
-    { name = "flake8", specifier = ">=6.1" },
-    { name = "isort", specifier = ">=5.12.0" },
-    { name = "pytest", specifier = ">=8.0" },
-    { name = "pytest-cov", specifier = ">=4.1" },
-    { name = "pytest-xdist", specifier = ">=3.0" },
-    { name = "teken", specifier = ">=0.8" },
-]
-
 [[package]]
 name = "execnet"
 version = "2.1.2"
@@ -256,6 +225,37 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/b3/38/89ba8ad64ae25be8de66a6d463314cf1eb366222074cfda9ee839c56a4b4/mdurl-0.1.2-py3-none-any.whl", hash = "sha256:84008a41e51615a49fc9966191ff91509e3c40b939176e643fd50a5c2196b8f8", size = 9979, upload-time = "2022-08-14T12:40:09.779Z" },
 ]
 
+[[package]]
+name = "microphone-cli"
+version = "0.8.2"
+source = { editable = "." }
+
+[package.dev-dependencies]
+dev = [
+    { name = "bandit" },
+    { name = "black" },
+    { name = "flake8" },
+    { name = "isort" },
+    { name = "pytest" },
+    { name = "pytest-cov" },
+    { name = "pytest-xdist" },
+    { name = "teken" },
+]
+
+[package.metadata]
+
+[package.metadata.requires-dev]
+dev = [
+    { name = "bandit", specifier = ">=1.7.5" },
+    { name = "black", specifier = ">=23.7.0" },
+    { name = "flake8", specifier = ">=6.1" },
+    { name = "isort", specifier = ">=5.12.0" },
+    { name = "pytest", specifier = ">=8.0" },
+    { name = "pytest-cov", specifier = ">=4.1" },
+    { name = "pytest-xdist", specifier = ">=3.0" },
+    { name = "teken", specifier = ">=0.8" },
+]
+
 [[package]]
 name = "mypy-extensions"
 version = "1.1.0"

microphone_cli-0.8.0/CLAUDE.md

@@ -1,28 +0,0 @@
-# CLAUDE.md — seed / bootstrap placeholder
-
-> **This is a self-initializing seed, not a finished runtime prompt.**
-> Run `/init` (or describe the agent's domain to your AI assistant) to
-> re-initialize this file into a full runtime prompt, using the description
-> below and the scaffolded repo as context.
-
-## Agent
-
-This repository hosts the **microphone-cli** agent.
-
-## Description
-
-Agent-first CLI for USB microphones and microphone arrays: enumerate devices, select and inspect channels, control gain and sample format, and read direction-of-arrival from array firmware.
-
-## Re-init instruction
-
-This file is a seed. To expand it into your full runtime prompt:
-
-1. Open this repo in Claude Code (or your preferred AI assistant).
-2. Run `/init` — the assistant will read the repo, incorporate the description
-   above, and replace this seed with a complete `CLAUDE.md`.
-3. Commit the result.
-
-Until you run `/init`, `microphone-cli` satisfies the `steward doctor`
-`prompt-file-present` and `backend-consistency` invariants (a `CLAUDE.md`
-exists and `culture.yaml` declares `backend: claude`) but the prompt is not
-yet tailored to this agent's domain.

microphone_cli-0.8.0/README.md

@@ -1,59 +0,0 @@
-# microphone-cli
-
-Agent-first CLI for USB microphones and microphone arrays: enumerate devices, select and inspect channels, control gain and sample format, and read direction-of-arrival from array firmware.
-
-## What you get
-
-- **An agent-first CLI** cited from [teken](https://github.com/agentculture/teken)
-  (`afi-cli`) — the runtime package has no third-party dependencies.
-- **A mesh identity** — `culture.yaml` (`suffix` + `backend`) and the matching
-  resident prompt file (`AGENTS.colleague.md`, since this template runs
-  `backend: colleague`).
-- **The canonical guildmaster skill kit** (11 skills) under `.claude/skills/`,
-  vendored cite-don't-import. See [`docs/skill-sources.md`](docs/skill-sources.md).
-- **A build + deploy baseline** — pytest, lint, the agent-first rubric gate, and
-  PyPI Trusted Publishing wired into GitHub Actions.
-
-## Quickstart
-
-```bash
-uv sync
-uv run pytest -n auto                 # run the test suite
-uv run microphone-cli whoami  # identity from culture.yaml
-uv run microphone-cli learn   # self-teaching prompt (add --json)
-uv run teken cli doctor . --strict    # the agent-first rubric gate CI runs
-```
-
-## CLI
-
-| Verb | What it does |
-|------|--------------|
-| `whoami` | Report this agent's nick, version, backend, and model from `culture.yaml`. |
-| `learn` | Print a structured self-teaching prompt. |
-| `explain <path>` | Markdown docs for any noun/verb path. |
-| `overview` | Read-only descriptive snapshot of the agent. |
-| `doctor` | Check the agent-identity invariants (prompt-file-present, backend-consistency). |
-| `cli overview` | Describe the CLI surface itself. |
-
-Every command supports `--json`. Results go to stdout, errors/diagnostics to
-stderr (never mixed). Exit codes: `0` success, `1` user error, `2` environment
-error, `3+` reserved.
-
-## Make it your own
-
-1. Rename the package `microphone_cli/` and the `microphone-cli`
-   CLI/dist name throughout `pyproject.toml`, the package, `tests/`,
-   `sonar-project.properties`, and this `README.md`. The name is hard-coded in
-   ~100 places, so list every occurrence first — see the `git grep` discovery
-   command in [`CLAUDE.md`](CLAUDE.md), the authoritative rename procedure.
-2. Edit `culture.yaml` with your `suffix` and `backend`.
-3. Rewrite `CLAUDE.md` for your agent and run `/init`.
-4. Re-vendor only the skills you need from guildmaster (see
-   [`docs/skill-sources.md`](docs/skill-sources.md)).
-
-See [`CLAUDE.md`](CLAUDE.md) for the full conventions (version-bump-every-PR,
-the `cicd` PR lane, deploy setup).
-
-## License
-
-Apache 2.0 — see [`LICENSE`](LICENSE).