docs: expand CLAUDE.md via /init and fix README command examples

[OriNachum]

What

Runs /init on the repo and fixes the README CLI examples that don't work today.

CLAUDE.md

Replaces the seed/bootstrap placeholder with a full runtime guide. Highlights:

• The three-form name split, called out up top because it's a live gotcha:
  the distribution/PyPI name is intern-cli, the import package is intern,
  and the console command is intern ([project.scripts] →
  intern = "intern.cli:main"). argparse's prog is intern-cli, so every
  --help/learn string says intern-cli while the runnable binary is
  intern.
• Honest framing that the shipped code is a clonable agent-first CLI
  template, not the Bonsai-SLM wrapper the package description advertises
  (no inference code exists yet).
• The main → register() → _dispatch flow, the recipe for adding a
  command/noun group, and the agent-first output contract (stdout/stderr split,
  --json everywhere, error:/hint: errors, exit-code policy).
• The culture.yaml + doctor identity model (this repo runs
  backend: colleague, so AGENTS.colleague.md — not CLAUDE.md — is the
  invariant-checked resident prompt).
• Version-bump-every-PR, the cicd lane, cite-don't-import skill vendoring,
  and the ~100-place rename procedure with the git grep discovery command the
  README already promised lived here.

README.md

• Quickstart invoked the CLI as intern-cli whoami / intern-cli learn — that
  binary doesn't exist, so the examples failed. Corrected to intern.
• Added a note under CLI clarifying command vs. dist vs. import-package
  names, and fixed the "Make it your own" rename step to reflect all three forms.

Why

The seed CLAUDE.md was still a placeholder, and the README's command examples
were broken (verified: uv run intern-cli whoami → No such file or directory;
uv run intern whoami works).

Verification

• uv run pytest -n auto — 22 passed
• uv run black --check / isort --check-only / flake8 / bandit — clean
• uv run teken cli doctor . --strict — 26/26 (rubric gate)
• uv run intern doctor — healthy
• markdownlint-cli2 on CLAUDE.md + README.md — 0 errors

Version bumped 0.4.0 → 0.4.1; uv.lock regenerated (its self-package entry
was stale at 0.3.4).

• intern-cli (Claude)

[OriNachum]

/agentic_review

[qodo-code-review]

Code Review by Qodo

New Review Started

This review has been superseded by a new analysis

[qodo-code-review]

PR Summary by Qodo

Docs: expand CLAUDE.md and fix README CLI command examples

📝 Documentation ⚙️ Configuration changes 🕐 10-20 Minutes

AI Description

• Replace seed CLAUDE.md with a full repo/runtime guide (naming, CLI flow, conventions).
• Fix README Quickstart to use the actual intern console command and clarify name forms.
• Bump version to 0.4.1 and add a matching changelog entry.

Diagram

graph TD
  Dev["Developer / user"] --> Readme["README.md"] --> Cmd["Console command: intern"] --> Entry["Python entry: intern.cli:main"] --> Prog["argparse prog: intern-cli"]
  Dev --> Claude["CLAUDE.md guide"] --> Cmd
  PyProj["pyproject.toml (name/scripts/version)"] --> Cmd

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Align argparse `prog` with console command (`intern`)

• ➕ Eliminates the intern-cli vs intern mismatch in --help output
• ➕ Reduces user confusion without relying on docs
• ➖ Potentially breaks tests/docs that assert on intern-cli in help text
• ➖ May be considered a breaking UX change if downstream tooling expects intern-cli strings

2. Ship an `intern-cli` wrapper script/alias

• ➕ Makes historical/README invocations work while preserving current internals
• ➕ Avoids changing argparse help text and existing string expectations
• ➖ Adds another supported entrypoint to maintain and document
• ➖ Can prolong ambiguity about which command is canonical

Recommendation: The PR’s documentation-first fix is the right minimal correction: it makes Quickstart work immediately and explicitly teaches the three-name split. If confusion continues, consider the follow-up option of aligning argparse prog to intern (cleaner UX) or adding an intern-cli shim (compatibility), but either should be evaluated for string-assert/test and downstream impact.

Files changed (4) +232 / -27

Documentation (3) +231 / -26

CHANGELOG.mdAdd 0.4.1 entry describing docs fixes and naming clarification +10/-0

Add 0.4.1 entry describing docs fixes and naming clarification

• Prepends a 0.4.1 release section capturing the CLAUDE.md expansion and the README CLI example fix (intern-cli vs intern).

CHANGELOG.md

CLAUDE.mdReplace seed placeholder with full runtime and workflow guide +209/-19

Replace seed placeholder with full runtime and workflow guide

• Replaces the bootstrap placeholder with a detailed guide covering the three-form naming split, CLI dispatch/register pattern, output contract, identity/doctor model, and repo conventions (version bump, CI, skill vendoring, renaming).

CLAUDE.md

README.mdFix Quickstart to run 'intern' and clarify naming forms +12/-7

Fix Quickstart to run 'intern' and clarify naming forms

• Updates broken Quickstart examples from 'intern-cli' to the actual 'intern' console command, adds a short clarification about dist vs import vs command names, and updates rename guidance to reflect all three name forms.

README.md

Other (1) +1 / -1

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

Bump project version to 0.4.1

• Updates the project version from 0.4.0 to 0.4.1 to satisfy the per-PR version bump policy.

pyproject.toml

[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) 📎 Requirement gaps (0)

Great, no issues found!

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