fix: make spanish the canonical CLI name; re-init CLAUDE.md

[OriNachum]

Why

CI's lint job runs uv run teken cli doctor . --strict — the agent-first rubric gate. It fails on main today, 25/26, so any PR opened against this repo starts red regardless of what it changes:

FAIL (error) explain_self: `explain spanish` exit=1
             hint: add an entry for 'spanish' (and the root) in the explain catalog

The rubric probes explain <console-script-name>. The console script is spanish ([project.scripts]), but the explain catalog only registered spanish-cli.

That mismatch was one symptom of a three-way name split left over from the template scaffold: script spanish, distribution spanish-cli, argparse prog spanish-cli. It also meant every error hint suggested spanish-cli explain spanish-cli — not a runnable command — and the README quickstart's uv run spanish-cli whoami exited 2 with Failed to spawn.

What changed

spanish becomes canonical for everything user- and agent-facing: argparse prog, the learn command map and its tool field, every explain-catalog body, and all hint: remediations.

spanish-cli is retained only where it is genuinely the right name:

Name	Where
spanish	the command; prog; learn; explain; hint: lines
spanish-cli	PyPI distribution (importlib.metadata), issues URL, mesh nick (culture.yaml suffix)

explain spanish-cli is kept as an alias to the root entry, so no documented path breaks.

Rolled in, because each was either caused by or blocking on the above:

• CLAUDE.md — replaced the self-initializing seed with a real runtime prompt: the stdout/stderr + CliError contract, the register(sub) extension path, the _CliArgumentParser._json_hint pre-parse mechanism, and the backend/prompt-file coupling. The seed asserted backend: claude; culture.yaml declares colleague, which makes AGENTS.colleague.md — not CLAUDE.md — this agent's resident prompt file.
• README.md — fixed the quickstart; replaced Make it your own, which cited a rename procedure that lived in the seed I replaced.
• uv.lock — pinned the workspace package at 0.3.4 while pyproject.toml declared 0.4.0. Re-locked at 0.5.0.

I deliberately did not rewrite the template prose ("a clonable template for AgentCulture mesh agents") that learn and explain still print. It is pre-existing, orthogonal to the naming fix, and belongs with the first real tutor feature. CLAUDE.md and the README now flag it explicitly.

Verification

teken cli doctor . --strict   26/26 passed, 0 errors, 0 warnings   (was 25/26)
pytest -n auto                23 passed                            (was 22)
black / isort / flake8 / bandit / markdownlint-cli2                clean

Exercised end-to-end, not just via tests:

$ uv run spanish explain spanish        # the rubric's self-probe
# spanish
$ uv run spanish explain spanish-cli    # dist-name alias still resolves
# spanish
$ uv run spanish explain bogus; echo "rc=$?"
error: no explain entry for: bogus
hint: list entries with: spanish explain spanish     # now runnable
rc=1
$ uv run spanish whoami 2>/dev/null      # stdout/stderr split intact
nick: spanish-cli                        # mesh nick, correctly unchanged

New test test_explain_dist_name_alias pins the alias; test_explain_self now probes the console-script name the rubric actually uses. test_learn_text was tightened from "spanish" in out (trivially true after the rename) to "spanish whoami" in out.

Notes for review

• devex pr lint reports one violation — user-dotfile-reference on CHANGELOG.md:32, the ~/.eidetic/memory prose in the shipped 0.4.0 entry. It is pre-existing (line 14 on main), shifted down by the entry this PR prepends; none of my 19 added changelog lines mention it. The rule targets code referencing user dotfiles, not a historical changelog, and devex pr lint is not part of CI. Not fixing — rewriting a released changelog entry to satisfy it would be worse.

• Alignment delta: this PR touches CLAUDE.md, so devex pr delta was run. No sibling follow-up needed — the vendored .claude/skills/ tree is untouched and the changes are spanish-cli-local.

• Version bumped 0.4.0 → 0.5.0 (minor: the CLI surface changes).

• spanish-cli (Claude)

[OriNachum]

/agentic_review

[qodo-code-review]

PR Summary by Qodo

Fix CLI self-name: make spanish canonical; keep spanish-cli as dist alias

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

AI Description

• Make spanish the canonical command name across CLI output, docs, and hints.
• Add explain spanish root entry and keep explain spanish-cli as a compatibility alias.
• Update docs/tests and bump version to 0.5.0 to match the corrected CLI surface.

Diagram

graph TD
  A["User / CI"] --> B["Console script: spanish"] --> C["CLI entry: spanish/cli/__init__.py"] --> D["Argparse prog/name"] --> E["Commands: whoami/learn/explain/..." ] --> F["Explain resolver: spanish/explain/__init__.py"] --> G["Explain catalog: spanish/explain/catalog.py"]
  E --> H["Tests: tests/test_cli*.py"]
  subgraph Legend
    direction LR
    _actor["Actor"] ~~~ _code["Python module"] ~~~ _test["Tests"]
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Minimal fix: add only `("spanish",)` explain entry

• ➕ Fastest change; minimal surface-area edits
• ➕ Unblocks the rubric gate immediately
• ➖ Leaves confusing mismatch across help/usage, learn text, and remediation hints
• ➖ README/quickstart remains broken (uv run spanish-cli ...)
• ➖ Doesn’t address the three-way name split that caused the failure

2. Dual-canonical naming (accept/print both names everywhere)

• ➕ Max backward-compatibility for users who learned spanish-cli
• ➕ Avoids forcing doc/test updates
• ➖ Ambiguous “official” name; increases long-term docs/support burden
• ➖ Makes rubric/self-probing behavior harder to reason about
• ➖ Encourages more drift across strings and catalogs over time

3. Rename console script to `spanish-cli` instead of canonicalizing `spanish`

• ➕ Aligns command name with distribution/repo name
• ➕ Could reduce conceptual load for packaging
• ➖ Breaks the existing console script expectation and the PR’s stated constraint (rubric probes console-script name)
• ➖ Would require downstream user command changes and potentially more disruptive compatibility work

Recommendation: Keep the PR’s approach: treat the console script (spanish) as the single canonical user/agent-facing name, and retain spanish-cli only for distribution identity and a targeted explain alias. This fixes the rubric failure at the root cause (name drift), makes remediation hints runnable, and preserves compatibility for explain spanish-cli without perpetuating dual naming across the whole CLI surface.

Files changed (16) +189 / -102

Bug fix (9) +61 / -56

__init__.pyMake argparse 'prog' and description use 'spanish' +2/-2

Make argparse 'prog' and description use 'spanish'

• Changes the top-level argparse program name and CLI description string from 'spanish-cli' to 'spanish' so help/usage and self-description match the console script.

spanish/cli/init.py

cli.pyUpdate 'cli' noun docs/help text to the 'spanish' command +5/-5

Update 'cli' noun docs/help text to the 'spanish' command

• Renames user-facing strings and docstrings from 'spanish-cli cli' to 'spanish cli', including the overview subject and help text, keeping the noun/verb rubric expectations intact.

spanish/cli/_commands/cli.py

doctor.pyUpdate doctor text output header to 'spanish' +2/-2

Update doctor text output header to 'spanish'

• Changes the text-mode doctor status header from 'spanish-cli doctor' to 'spanish doctor' so printed output matches the canonical command name.

spanish/cli/_commands/doctor.py

explain.pyUpdate explain help text to reference 'spanish' as root +2/-2

Update explain help text to reference 'spanish' as root

• Adjusts the help string so the empty explain path is described as the 'spanish' root, aligning user guidance with the canonical console script name.

spanish/cli/_commands/explain.py

learn.pyCanonicalize 'learn' text and JSON tool name to 'spanish' +11/-11

Canonicalize 'learn' text and JSON tool name to 'spanish'

• Updates the learn prompt’s command map and explain pointer to use 'spanish', and changes the JSON payload 'tool' field accordingly so agents receive the runnable command name.

spanish/cli/_commands/learn.py

overview.pyUpdate overview subject to 'spanish' +2/-2

Update overview subject to 'spanish'

• Changes the overview subject header from 'spanish-cli' to 'spanish' for consistent self-description in both human and JSON modes.

spanish/cli/_commands/overview.py

whoami.pyUpdate whoami docstring to 'spanish' +1/-1

Update whoami docstring to 'spanish'

• Updates the command docstring from 'spanish-cli whoami' to 'spanish whoami', matching the canonical CLI name without altering identity semantics (mesh nick remains 'spanish-cli').

spanish/cli/_commands/whoami.py

__init__.pyFix unknown-explain remediation hint to a runnable 'spanish' command +1/-1

Fix unknown-explain remediation hint to a runnable 'spanish' command

• Updates the remediation hint for missing explain entries to suggest 'spanish explain spanish' instead of a non-runnable 'spanish-cli ...' command line.

spanish/explain/init.py

catalog.pyCanonicalize root explain entry to 'spanish' and add 'spanish-cli' alias +35/-30

Canonicalize root explain entry to 'spanish' and add 'spanish-cli' alias

• Renames markdown headers and command examples throughout the catalog to 'spanish'. Adds '("spanish",)' as the canonical root key (for rubric 'explain_self') while retaining '("spanish-cli",)' as an alias for the distribution name.

spanish/explain/catalog.py

Tests (2) +19 / -11

test_cli.pyUpdate CLI tests for canonical name and add dist-name alias coverage +14/-6

Update CLI tests for canonical name and add dist-name alias coverage

• Updates assertions to expect 'usage: spanish', 'tool: spanish', and '# spanish' headings. Changes 'test_explain_self' to probe 'explain spanish' (console-script name) and adds 'test_explain_dist_name_alias' to ensure 'explain spanish-cli' still resolves to the root.

tests/test_cli.py

test_cli_introspection.pyUpdate introspection tests to expect 'spanish' subjects/headings +5/-5

Update introspection tests to expect 'spanish' subjects/headings

• Adjusts overview/cli overview/doctor assertions so text and JSON subjects use 'spanish' consistently across introspection commands.

tests/test_cli_introspection.py

Documentation (4) +108 / -34

CHANGELOG.mdAdd 0.5.0 release notes for canonical CLI name + docs/lock fixes +18/-0

Add 0.5.0 release notes for canonical CLI name + docs/lock fixes

• Prepends a 0.5.0 entry documenting the 'spanish' canonical CLI name change, the 'explain' alias behavior, the CLAUDE.md/README updates, and the uv.lock mismatch fix.

CHANGELOG.md

CLAUDE.mdReplace bootstrap seed with a runtime prompt and repo conventions +76/-19

Replace bootstrap seed with a runtime prompt and repo conventions

• Replaces the placeholder seed with a full working prompt describing the rubric gate, CLI error/output contracts, extension points ('register(sub)'), backend/prompt-file coupling, and version-bump conventions. Clarifies that the canonical command is 'spanish' while 'spanish-cli' remains the distribution/mesh nick, and documents the 'explain spanish-cli' alias intent.

CLAUDE.md

README.mdFix quickstart to use 'uv run spanish' and remove rename-seed instructions +13/-14

Fix quickstart to use 'uv run spanish' and remove rename-seed instructions

• Updates the quickstart commands from 'spanish-cli' to 'spanish' and adds a short note explaining command vs distribution naming. Replaces the template rename procedure section with a status note about the repo still being a scaffold.

README.md

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

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

• Adjusts the comment documenting exit codes to point to 'spanish learn' output, keeping inline docs consistent with the canonical command name.

spanish/cli/_errors.py

Other (1) +1 / -1

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

Bump project version to 0.5.0

• Updates the declared package version from 0.4.0 to 0.5.0 to reflect the CLI surface change and accompanying documentation/testing updates.

pyproject.toml

[qodo-code-review]

Code Review by Qodo

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

Context used

✅ Compliance rules (platform): 4 rules

✅ Skills: version-bump

1. Stale pytest count ✓ Resolved 🐞 Bug ⚙ Maintainability

Description

CLAUDE.md states pytest -n auto runs the “full suite (22 tests)”, but the repo currently
contains 23 test functions, so this guidance is already out of date and can confuse local
verification.

Code

CLAUDE.md[18]

+uv run pytest -n auto                     # full suite (22 tests, ~1s)

Evidence

The command comment in CLAUDE.md says the suite is 22 tests, but the test suite currently includes
13 tests in tests/test_cli.py and 10 in tests/test_cli_introspection.py, totaling 23.

CLAUDE.md[15-20]
tests/test_cli.py[14-123]
tests/test_cli_introspection.py[14-106]

Agent prompt

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

### Issue description
`CLAUDE.md` hard-codes the pytest suite size as “22 tests”, but the repository currently has 23 tests. This makes the repo guidance stale immediately after this PR.

### Issue Context
The PR added/updated CLI tests, so the test count changed; keeping an exact number in docs will keep drifting.

### Fix Focus Areas
- CLAUDE.md[15-20]

### Proposed fix
Either:
1) Update the comment to the current count (23), **or**
2) Preferably remove the exact number and keep only an approximate runtime (e.g., `# full suite (~1s)`).

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

---

[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