docs: re-init CLAUDE.md from seed into a full runtime prompt

[OriNachum]

Summary

Runs /init — replaces the bootstrap seed CLAUDE.md (agent description + a
"run /init" instruction) with a runtime prompt derived from how the code
actually behaves, verified by running it — and fixes the CI failure that
reading the repo turned up.

Two commits:

1. docs: re-init CLAUDE.md from the seed.
2. fix: settle the CLI name split, turning CI's lint job green.

The CI lint job was red on main

uv run teken cli doctor . --strict (a CI gate) exited 1 on a clean
checkout, and had since the template rename:

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

The agent-first rubric resolves the tool's own name from [project.scripts]
(→ french) and requires explain <that name> to resolve, but
french/explain/catalog.py keyed its root entry only on ("french-cli",), and
the argparse prog disagreed with the installed script as well.

Resolution — two names, on purpose, with a stated rule:

	Name
Invocations — console script, argparse prog, usage lines, command maps, explain paths, help text	french
Identity — distribution / PyPI, repo, culture.yaml mesh nick, _FALLBACK_NICK, _pkg_version, overview subject, doctor header	french-cli

• The catalog root now resolves under both ("french",) and ("french-cli",).
• learn --json exposes both: the existing tool field (distribution) plus a
  new command field (what to invoke).
• test_explain_self asserts both names resolve, and a new
  test_explain_self_matches_console_script pins the catalog key to the console
  script so the regression can't recur silently.

Rubric goes 25/26 (exit 1) → 26/26 (exit 0).

Also fixed

• README.md documented a command that doesn't exist — uv run french-cli whoami.
  Quickstart and the CLI table now show the real command, french.
• README.md's "Make it your own" section was cloner boilerplate (this repo
  is the clone), and its step 1 pointed at a git grep discovery command "in
  CLAUDE.md" that never existed there. Replaced with a Status section stating
  plainly that the tutor domain is unbuilt.
• uv.lock had drifted — still pinned french-cli 0.3.4 while
  pyproject.toml declared 0.4.0 (the 0.4.0 bump never re-locked).

What the new CLAUDE.md captures

• The French-tutor domain is not implemented. Every verb is still generic
  introspection. Said up front so the next session doesn't hunt for a domain
  layer that was never written.
• The agent-first rubric is a contract, not style, which makes several
  apparently-dead constructs load-bearing: overview's ignored target
  positional (descriptive verbs must not hard-fail on a bad path), the cli
  noun group (any noun with action-verbs must expose overview), and
  _CliArgumentParser._json_hint (argparse parse errors fire before
  args.json exists).
• backend: colleague → AGENTS.colleague.md, enforced jointly by
  doctor.py's _PROMPT_FILE map and test_doctor_recognizes_declared_backend.
  CLAUDE.md guides Claude Code; AGENTS.colleague.md is the resident prompt.
  The seed had re-introduced the stale backend: claude claim that 0.3.4
  corrected elsewhere.
• type: command in a vendored SKILL.md is load-bearing —
  core.skill_loader silently skips a SKILL.md without it.
• Version-bump-every-PR, cite-don't-import for .claude/skills/, and why
  [tool.coverage.run] relative_files = true is not decorative.

Verification

uv run pytest -n auto                      23 passed
black --check / isort --check-only         clean
flake8 / bandit                            clean
markdownlint-cli2 CLAUDE/CHANGELOG/README  0 errors
teken cli doctor . --strict                26/26 healthy, exit 0

devex pr lint reports one user-dotfile-reference violation on the
~/.eidetic/memory line inside the shipped 0.4.0 changelog entry
(main:CHANGELOG.md:14); my insert only shifted its line number. I won't
rewrite released changelog history to satisfy a portability rule on descriptive
prose, and devex pr lint is not one of CI's gates.

Alignment-delta: no .claude/skills/ or culture.yaml change, so no sibling
follow-up is owed.

Version bumped 0.4.0 → 0.4.1.

🤖 Generated with Claude Code

https://claude.ai/code/session_019pZenu1fqrz35Hxh9m5VjW

[OriNachum]

/agentic_review

[qodo-code-review]

PR Summary by Qodo

Re-initialize CLAUDE.md into a runtime prompt and bump version to 0.4.1

📝 Documentation ⚙️ Configuration changes 🕐 20-40 Minutes

AI Description

• Replace bootstrap CLAUDE.md seed with a repository-specific runtime prompt.
• Document known repo/CI behavior and constraints to avoid rediscovery in future sessions.
• Bump project version to 0.4.1 and record the change in CHANGELOG.md.

Diagram

graph TD
  Dev["Contributor"] --> CLAUDE["CLAUDE.md"] --> CC["Claude Code guidance"]
  Dev --> PYPROJ["pyproject.toml"] --> CI["CI version-check"]
  Dev --> CHANGELOG["CHANGELOG.md"] --> NOTES["Release notes"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Keep CLAUDE.md minimal and move details to /docs

• ➕ Keeps the Claude Code entrypoint short and easier to maintain
• ➕ Allows deeper sections (rubric rationale, known defects) to live in conventional docs
• ➖ Claude Code may be less likely to read linked docs during interactive work
• ➖ Increases the chance key constraints are missed during sessions

2. Split into CLAUDE.md (Claude Code) and AGENTS.* prompt docs only

• ➕ Clarifies separation between editor guidance and runtime agent prompts
• ➕ Reduces risk of conflating backend prompt behavior with Claude Code behavior
• ➖ Requires careful curation of overlap to avoid duplication/drift
• ➖ May fragment critical context across multiple files

Recommendation: The PR’s approach (make CLAUDE.md a full, repo-accurate runtime prompt) is appropriate for minimizing rediscovery cost during future sessions. If it becomes hard to keep current, consider extracting the longest explanatory sections into docs while leaving a concise, high-signal checklist and links in CLAUDE.md.

Files changed (3) +253 / -20

Documentation (2) +252 / -19

CHANGELOG.mdAdd 0.4.1 entry documenting CLAUDE.md re-init and known defects +49/-0

Add 0.4.1 entry documenting CLAUDE.md re-init and known defects

• Adds a new 0.4.1 release section describing the CLAUDE.md re-initialization into a runtime prompt and explicitly recording two known, pre-existing defects. Also notes the rationale and key behavioral/contracts the prompt captures.

CHANGELOG.md

CLAUDE.mdReplace bootstrap seed with full runtime prompt for Claude Code +203/-19

Replace bootstrap seed with full runtime prompt for Claude Code

• Replaces the minimal seed file with detailed, repo-specific guidance: current repo reality, command/CI gates, known rubric failure details, and architectural constraints (agent-first contract, identity/backend prompt mapping, and vendored skills conventions). Emphasizes the separation between Claude Code guidance and the colleague backend’s resident prompt file.

CLAUDE.md

Other (1) +1 / -1

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

Bump project version from 0.4.0 to 0.4.1

• Updates the project version to 0.4.1 to satisfy the repo’s version-bump-per-PR convention and align with the new changelog entry.

pyproject.toml

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Great, no issues found!

Qodo reviewed your code and found no material issues that require review

[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