docs: re-init CLAUDE.md; make CLI command name consistent (harmonics)

[OriNachum]

What

Two related changes, driven by /init:

1. Re-initialize CLAUDE.md from the bootstrap seed into a full runtime
   prompt. It now carries the harmonics non-TTS-audio mission and the
   intent → sound design-spine table from
   #1, the agent-first
   CLI architecture (the register(sub) pattern, the stdout/stderr + CliError

   • --json output contract, the tuple-keyed explain catalog, the doctor
     rubric invariants), the uv build/test/lint commands, and the
     identity / version-bump / cite-don't-import conventions.

2. Reconcile the command-name split. The README quickstart showed
   uv run harmonics-cli whoami, which fails — the console script is
   harmonics. Rather than rename the script, this keeps the short command
   harmonics (matching the culture / teken / devex convention) and
   fixes the docs to match it.

The naming rule

• Runnable commands → harmonics <verb>: README quickstart, learn
  output, explain catalog (verb-page headings + usage blocks), argparse
  prog, doctor's status header, cli overview's subject, module docstrings.
• Bare product / identity → stays harmonics-cli: the PyPI dist name
  (uv tool install harmonics-cli), the culture nick, the root explain /
  overview page titles, and learn's JSON tool field.
• Added harmonics as a root explain topic alias, so
  harmonics explain harmonics resolves alongside
  harmonics explain harmonics-cli (and the afi rubric's explain_self check,
  which probes explain <prog>, passes).

Verification

• pytest -n auto — 22 passed (updated the 5 assertions that pinned the old
  command-form strings).
• black / isort / flake8 / bandit — clean.
• markdownlint-cli2 — clean.
• teken cli doctor . --strict (afi rubric gate) — PASS.

Version bumped 0.4.0 → 0.4.1; uv.lock re-synced.

Note: this PR touches CLAUDE.md but nothing under .claude/skills/ or
culture.yaml, so no sibling alignment delta is expected. The scaffold's
self-description strings ("a clonable template …" in prog/learn/catalog)
are intentionally left for the domain build — swapping them for the real
harmonics mission belongs with the first audio verb, not this naming pass.

• harmonics-cli (Claude)

[OriNachum]

/agentic_review

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 📜 Skill insights (0)

Context used

✅ Tickets: 🎫 harmonics-cli — build brief (onboarding / source of truth)

1. Changelog version mismatch ✓ Resolved 🐞 Bug ⚙ Maintainability

Description

The 0.4.1 changelog entry states that uv.lock was re-synced to the “0.4.0 project version”, but
pyproject.toml bumps the project to 0.4.1. This makes the release notes internally inconsistent
and can confuse downstream readers about what was actually released.

Code

CHANGELOG.md[R15-17]

+### Fixed
+
+- Re-synced uv.lock to the 0.4.0 project version and recorded resolved dev-dependency entries (execnet, flake8).

Evidence

The changelog text explicitly references “0.4.0 project version” under the 0.4.1 release heading,
while the project version is set to 0.4.1 in pyproject.toml in the same PR.

CHANGELOG.md[8-17]
pyproject.toml[1-4]

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 0.4.1 changelog entry claims `uv.lock` was re-synced to the “0.4.0 project version”, which conflicts with the 0.4.1 version bump in `pyproject.toml`.

## Issue Context
This is a release-notes accuracy problem (not runtime behavior), but it makes the changelog confusing/inaccurate.

## Fix Focus Areas
- CHANGELOG.md[15-17]

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

---

[qodo-code-review]

PR Summary by Qodo

Docs: re-init CLAUDE.md and align CLI command name to harmonics

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

AI Description

• Expand CLAUDE.md into a full runtime prompt describing mission, architecture, and conventions.
• Standardize runnable CLI examples and UI strings to harmonics  (not harmonics-cli).
• Add harmonics as an explain root alias and update tests to match.

Diagram

graph TD
  U["User / agent"] --> CLI["Console script: harmonics"] --> P["Argparse parser (prog=harmonics)"] --> C["Command modules (_commands/*)"] --> O["Output contract (text/--json)"]
  C --> E["explain command"] --> K[("Explain catalog (tuple keys)")]
  K --> A["Root alias: ('harmonics',) + ('harmonics-cli',)"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Rename the console script to `harmonics-cli`

• ➕ Eliminates the command/dist split entirely
• ➕ Avoids needing aliasing and doc rules
• ➖ Breaks existing users and the short-name convention (culture/teken/devex)
• ➖ Would likely require deprecation/migration messaging and dual support anyway

2. Ship both entry points (`harmonics` and `harmonics-cli`)

• ➕ Backwards-compatible for anyone already using harmonics-cli examples
• ➕ Reduces user confusion when searching/guessing the command name
• ➖ Ongoing maintenance of two public commands
• ➖ Increases documentation surface and ambiguity about the canonical invocation

3. Keep `harmonics` canonical but add a lightweight runtime hint

• ➕ If users run harmonics-cli and it exists, can guide them to harmonics
• ➕ Improves UX without expanding docs further
• ➖ Requires intentionally publishing/maintaining the harmonics-cli script (similar to dual entry points)
• ➖ Still leaves two names in circulation

Recommendation: Keep the PR’s approach: treat harmonics as the canonical runnable command and make all runnable examples consistent, while keeping harmonics-cli as the dist/identity name. Adding the explain root alias is a pragmatic compatibility measure that preserves the rubric-driven explain behavior without introducing a second console script.

Files changed (16) +257 / -79

Enhancement (1) +38 / -30

catalog.pyAdd '('harmonics',)' root alias and update catalog markdown headings/usages +38/-30

Add '('harmonics',)' root alias and update catalog markdown headings/usages

• Updates the catalog’s documentation to describe the command/dist naming rule, switches runnable examples/headings to 'harmonics …', and adds '('harmonics',)' as an additional key resolving to the root entry alongside '()' and '('harmonics-cli',)'. This preserves root explain lookups under both tokens.

harmonics/explain/catalog.py

Bug fix (8) +22 / -21

__init__.pySet argparse 'prog' to 'harmonics' for correct usage/help text +1/-1

Set argparse 'prog' to 'harmonics' for correct usage/help text

• Changes the CLI parser’s displayed program name from 'harmonics-cli' to 'harmonics', aligning '--help' and parse error usage output with the actual console script name.

harmonics/cli/init.py

cli.pyAlign 'cli' noun overview subject/help text with 'harmonics' +4/-4

Align 'cli' noun overview subject/help text with 'harmonics'

• Updates module docstring, overview subject string, and help text to reference 'harmonics cli …' instead of 'harmonics-cli cli …'. Keeps behavior the same while making surfaced text consistent.

harmonics/cli/_commands/cli.py

doctor.pyUpdate doctor header/docstring to 'harmonics doctor' +2/-2

Update doctor header/docstring to 'harmonics doctor'

• Adjusts the doctor command’s module docstring and the human-readable status header from 'harmonics-cli doctor' to 'harmonics doctor', matching the executable name users run.

harmonics/cli/_commands/doctor.py

explain.pyUpdate explain docs/help to reference 'harmonics' root token +2/-2

Update explain docs/help to reference 'harmonics' root token

• Updates the explain command’s docstring and argument help text so the empty path/root guidance references 'harmonics' rather than 'harmonics-cli'.

harmonics/cli/_commands/explain.py

learn.pyUpdate learn text and JSON pointer to 'harmonics' command form +10/-9

Update learn text and JSON pointer to 'harmonics' command form

• Edits the learn prompt’s command map to use 'harmonics <verb>' examples and changes the explain pointer in JSON payload to 'harmonics explain <path>'. Adds an explicit note that the dist name is 'harmonics-cli' but the runnable command is 'harmonics'.

harmonics/cli/_commands/learn.py

overview.pyUpdate overview command docstring to 'harmonics overview' +1/-1

Update overview command docstring to 'harmonics overview'

• Changes the module docstring to reflect the canonical runnable command name ('harmonics'). No functional changes.

harmonics/cli/_commands/overview.py

whoami.pyUpdate whoami command docstring to 'harmonics whoami' +1/-1

Update whoami command docstring to 'harmonics whoami'

• Adjusts the module docstring to match the canonical command name. No behavioral changes.

harmonics/cli/_commands/whoami.py

__init__.pyUpdate unknown-path remediation message to 'harmonics explain harmonics' +1/-1

Update unknown-path remediation message to 'harmonics explain harmonics'

• Adjusts the remediation hint emitted on missing explain entries so it points to the canonical command name when listing catalog entries.

harmonics/explain/init.py

Refactor (1) +1 / -1

_errors.pyUpdate exit-code policy comment reference to 'harmonics learn' +1/-1

Update exit-code policy comment reference to 'harmonics learn'

• Updates an internal comment so the documentation pointer references 'harmonics learn' rather than 'harmonics-cli learn'.

harmonics/cli/_errors.py

Tests (2) +5 / -5

test_cli.pyUpdate CLI tests for new usage/prog and explain markdown strings +2/-2

Update CLI tests for new usage/prog and explain markdown strings

• Adjusts assertions to expect 'usage: harmonics' and to verify 'explain' markdown contains 'harmonics whoami' instead of 'harmonics-cli whoami'. Ensures tests remain aligned with the new public-facing strings.

tests/test_cli.py

test_cli_introspection.pyUpdate introspection tests for 'cli overview' subject and doctor header +3/-3

Update introspection tests for 'cli overview' subject and doctor header

• Updates expectations for the 'cli overview' subject/header and doctor text output to use 'harmonics …' instead of 'harmonics-cli …'. Keeps the test coverage of introspection output shape intact.

tests/test_cli_introspection.py

Documentation (3) +190 / -21

CHANGELOG.mdAdd 0.4.1 entry documenting CLAUDE.md re-init and command-name standardization +11/-0

Add 0.4.1 entry documenting CLAUDE.md re-init and command-name standardization

• Introduces a new 0.4.1 section describing the CLAUDE.md expansion and the 'harmonics' vs 'harmonics-cli' naming rule. Notes the documentation and CLI-surface string updates as part of the release narrative.

CHANGELOG.md

CLAUDE.mdReplace bootstrap seed with full Claude Code runtime guidance +174/-19

Replace bootstrap seed with full Claude Code runtime guidance

• Expands CLAUDE.md into a detailed runtime prompt: harmonics mission/context, intent→sound design spine, uv-based dev commands, and agent-first CLI architecture and contracts. Documents the command/dist name split and the conventions for where each name should appear.

CLAUDE.md

README.mdFix quickstart to use 'uv run harmonics …' and clarify dist vs command +5/-2

Fix quickstart to use 'uv run harmonics …' and clarify dist vs command

• Updates the quickstart examples from 'harmonics-cli' to the runnable 'harmonics' command. Adds a short clarification that the PyPI package is 'harmonics-cli' while the executable is 'harmonics'.

README.md

Other (1) +1 / -1

pyproject.tomlBump project version to 0.4.1 +1/-1

Bump project version to 0.4.1

• Increments the package version from 0.4.0 to 0.4.1 to reflect the documentation and CLI-surface consistency release.

pyproject.toml

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud