docs: re-init CLAUDE.md and correct README command names

[OriNachum]

What

Runs /init on this repo: replaces the seed CLAUDE.md placeholder with a real
runtime prompt, and corrects README.md — which documented a command that does
not exist.

Why

CLAUDE.md shipped as the template's self-initializing seed. It carried two
inaccuracies: it told readers to run /init to produce the real file, and it
asserted that culture.yaml declares backend: claude. It declares
colleague — which is why AGENTS.colleague.md is the resident prompt file
doctor checks for.

The README quickstart was broken. pyproject.toml declares the console script
as microphone, not microphone-cli:

$ uv run microphone-cli whoami
error: Failed to spawn: `microphone-cli`
  Caused by: No such file or directory (os error 2)

CLAUDE.md

Written for what a future instance actually needs and cannot get from one file:

• Current state — this is the renamed template scaffold; no microphone
  domain code exists yet. Names the specific files still carrying template prose
  (learn.py, overview.py's _ARTIFACTS, explain/catalog.py) so they get
  rewritten rather than quietly shipped.
• Commands — install, full/single-file/single-test pytest, the four-tool CI
  lint set, markdownlint, and teken cli doctor . --strict.
• Architecture — the register(sub) dispatch pattern; the three contracts
  the rubric gate enforces (CliError so no traceback escapes, the strict
  stdout/stderr split, --json everywhere); the _CliArgumentParser /
  _json_hint mechanism and the easy-to-miss parser_class=type(p)
  propagation for nested nouns; and why whoami walks up from __file__
  rather than the CWD.
• Adding a verb or noun — including the two non-obvious gates: every command
  path needs an explain/catalog.py entry (a test walks all keys), and any noun
  with action-verbs must also expose <noun> overview.
• CI/release and vendored skills — version-bump-every-PR, the publish flow,
  and don't-hand-edit-.claude/skills/.

README

Commands now use microphone, with a note that argparse still prints
microphone-cli as the program name in --help. Also: a scaffold-status
banner, the stale skill count dropped (said 11; there are 19 vendored
directories), the backend line rewritten to describe this agent rather than the
template, and the template-only "Make it your own" rename section replaced with
a Development section.

Known inconsistency, not fixed here

The console script is microphone but every doc string, help line, learn
payload, and explain entry says microphone-cli. Renaming either side touches
~100 strings and several test assertions ("usage: microphone-cli"), so this PR
documents the mismatch rather than picking a side. Worth its own PR.

Verification

• uv run pytest -q — 22 passed
• uv run teken cli doctor . --strict — all rubric bundles pass
• markdownlint-cli2 on the three changed docs — 0 errors
• devex pr lint — no violations
• devex pr delta — ran per the alignment-delta rule (this PR touches
  CLAUDE.md); no sibling drift, no follow-up PRs needed

Docs-only; version bumped 0.8.0 → 0.8.1 per the every-PR rule.

• microphone-cli (Claude)

[OriNachum]

/agentic_review

[qodo-code-review]

PR Summary by Qodo

Initialize Claude guidance and correct README command names

📝 Documentation 🐞 Bug fix ⚙️ Configuration changes 🕐 10-20 Minutes

AI Description

• Replace seed Claude guidance with repository architecture, workflows, and contribution contracts.
• Correct runnable README examples to use the declared microphone console script.
• Document scaffold status and publish release metadata for version 0.8.1.

Diagram

graph TD
  CFG["Project Metadata"] -->|declares script| README["README Quickstart"] --> USER["CLI Users"]
  CFG -->|syncs version| LOCK["Lockfile"]
  CFG -->|records release| LOG["Changelog"]
  CLI["CLI Architecture"] -->|documents contracts| GUIDE["Claude Guidance"] --> DEV["Contributors"]
  CFG -->|informs setup| GUIDE

Loading

High-Level Assessment

The scoped documentation correction is appropriate: it immediately fixes broken quickstart commands while clearly disclosing the remaining console-script versus argparse prog inconsistency. Unifying those names was reasonably deferred because it would create a broader behavioral change across approximately 100 strings and multiple test assertions.

Files changed (5) +215 / -69

Bug fix (1) +30 / -18

README.mdFix runnable commands and clarify scaffold status +30/-18

Fix runnable commands and clarify scaffold status

• Changes quickstart commands from the nonexistent 'microphone-cli' executable to 'microphone', while explaining the remaining argparse display-name mismatch. Adds scaffold status and development guidance, corrects backend wording, and removes the stale skill count and template rename instructions.

README.md

Documentation (2) +153 / -19

CHANGELOG.mdRecord the 0.8.1 documentation corrections +11/-0

Record the 0.8.1 documentation corrections

• Adds the 0.8.1 release entry describing the initialized Claude guidance, corrected README commands, and fixed backend-to-prompt mapping.

CHANGELOG.md

CLAUDE.mdReplace the bootstrap seed with repository runtime guidance +142/-19

Replace the bootstrap seed with repository runtime guidance

• Replaces the self-initializing placeholder with detailed guidance covering scaffold status, commands, CLI dispatch and output contracts, identity handling, extension requirements, CI and release workflows, and vendored skills. It also documents the actual 'microphone' executable and the 'colleague' backend mapping.

CLAUDE.md

Other (2) +32 / -32

pyproject.tomlBump the project version to 0.8.1 +1/-1

Bump the project version to 0.8.1

• Advances the package version from 0.8.0 to 0.8.1 to satisfy the repository's release policy for every PR.

pyproject.toml

uv.lockSynchronize editable package metadata at 0.8.1 +31/-31

Synchronize editable package metadata at 0.8.1

• Updates the local 'microphone-cli' package entry to version 0.8.1. Dependency requirements remain unchanged; the entry moves according to lockfile ordering.

uv.lock

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📜 Skill insights (0)

1. Version downgrades pass review checks ✓ Resolved 🐞 Bug ☼ Reliability

Description

CLAUDE.md says version-check enforces a version bump, but the workflow only rejects equality
with the version on the main branch. A contributor who accidentally changes 0.8.1 to 0.8.0
therefore sees this check pass despite the newly documented safeguard.

Code

CLAUDE.md[R129-131]

+**Every PR bumps the version — including docs-, config-, and CI-only PRs.**
+`version-check` compares `pyproject.toml` against `origin/main` and fails the PR
+otherwise. Use the `version-bump` skill (or edit `pyproject.toml` +

Evidence

The added guidance states that every PR bumps the version and that the check enforces this policy.
The workflow reads both versions but tests only string equality, allowing every unequal lower
version through the version-check job.

CLAUDE.md[129-133]
README.md[63-64]
.github/workflows/tests.yml[97-111]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The documentation promises that CI enforces version bumps, while the workflow accepts any version that differs from main, including a downgrade.

## Issue Context
Compare versions semantically and reject equal or lower values, or narrow the documentation so it accurately describes the weaker check.

## Fix Focus Areas
- .github/workflows/tests.yml[97-111]
- CLAUDE.md[129-133]
- README.md[63-64]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Fresh checkouts cannot run Markdown lint ✓ Resolved 🐞 Bug ≡ Correctness

Description

CLAUDE.md presents markdownlint-cli2 as a runnable development command, but uv sync does not
install that executable. On a fresh development environment, following the documented setup reaches
a command-not-found failure before the Markdown checks can run.

Code

CLAUDE.md[37]

+markdownlint-cli2 "**/*.md" "#node_modules" "#.local" "#.claude/skills"

Evidence

The documented setup only installs the Python development dependencies, whose list does not include
this npm executable. CI explicitly installs markdownlint-cli2@0.21.0 before invoking the same
command, proving that an additional setup step is required.

CLAUDE.md[24-38]
pyproject.toml[32-42]
.github/workflows/tests.yml[69-72]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The documented Markdown lint command is unavailable after the preceding `uv sync` setup because CI installs `markdownlint-cli2` separately with npm.

## Issue Context
Make the local instructions self-contained and align the tool version with CI, either by documenting the npm installation step or using an equivalent pinned invocation.

## Fix Focus Areas
- CLAUDE.md[24-38]
- .github/workflows/tests.yml[69-72]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Context sources

Review mode: ⚖️ Balanced: Although primarily documentation, the PR also changes project version metadata and the lockfile, and the extensive runtime guidance contains many independently verifiable command, architecture, and CI claims.

Tip of the day

💡 Did you know, you can show, collapse, or hide each part of a finding: code, evidence, and all

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud