docs: expand CLAUDE.md from seed into full runtime guide

[OriNachum]

What

Runs /init to replace the bootstrap-seed CLAUDE.md with a complete runtime guide for future Claude Code instances.

Why

The repo shipped with the placeholder seed CLAUDE.md (the culture-agent-template bootstrap). This expands it into real guidance grounded in the actual code.

Highlights

• States the true repo state: still the template scaffold — no tensor-domain logic exists yet despite the description. Domain work is greenfield (add as new noun groups).
• Architecture: the register(sub) dispatch contract, the CliError/no-traceback error contract, the strict stdout/stderr split, --json everywhere, the explain catalog, and the load-bearing agent-first rubric (teken cli doctor . --strict) that dictates why the introspection verbs exist.
• Console-script gotcha: the installed executable is tensor, not tensor-cli (the README's uv run tensor-cli … examples fail). Flagged, not silently "fixed."
• Conventions: version-bump-every-PR, the cicd lane, the relative_files SonarCloud coverage requirement, cite-don't-import skill kit, and the clone/rename procedure the README delegates here.

Verification

• uv run pytest -n auto — 21 passed
• uv run teken cli doctor . --strict — rubric gate green
• markdownlint-cli2 on changed .md — 0 errors
• tensor doctor — healthy
• Version bumped 0.2.0 -> 0.2.1 (CHANGELOG + pyproject + uv.lock)

Note: the alignment-delta step couldn't run (.claude/skills.local.yaml not configured on this machine), but the change is self-contained to this repo's own CLAUDE.md — no skill bodies or shared conventions touched, so no sibling propagation is needed.

• tensor-cli (Claude)

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (1) 📘 Rule violations (1)

Context used

✅ Compliance rules (platform): 1 rule

1. No alignment delta check noted 📘 Rule violation ≡ Correctness

Description

This PR modifies CLAUDE.md, which triggers the requirement to run a sibling alignment delta check
and note any impacted siblings needing follow-up PRs. The provided PR info indicates the
alignment-delta step was not run, which violates the checklist requirement.

Code

CLAUDE.md[R1-3]

+# CLAUDE.md

-> **This is a self-initializing seed, not a finished runtime prompt.**
-> Run `/init` (or describe the agent's domain to your AI assistant) to
-> re-initialize this file into a full runtime prompt, using the description
-> below and the scaffolded repo as context.
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Evidence

The checklist mandates an alignment delta check for PRs modifying CLAUDE.md. The diff shows
CLAUDE.md was significantly modified, so the requirement applies, but the PR info states the delta
check was not run.

Rule 920115: Run alignment delta check when PR modifies skill or agent config files
CLAUDE.md[1-3]

Agent prompt

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

## Issue description
This PR changes `CLAUDE.md`, which requires running the sibling alignment delta check and explicitly noting any sibling repos that require follow-up PRs.

## Issue Context
Compliance requires that when `CLAUDE.md`, `culture.yaml`, or files under `.claude/skills/` are modified, a sibling alignment delta check is performed (e.g., `workflow.sh delta`) and any impacted sibling is called out in the PR review reply.

## Fix Focus Areas
- CLAUDE.md[1-3]

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

---

2. Markdownlint setup undocumented 🐞 Bug ≡ Correctness

Description

CLAUDE.md lists markdownlint-cli2 as part of the required lint suite but doesn’t document how to
install it, so running the documented lint commands on a fresh checkout will fail with a missing
command error. CI installs markdownlint-cli2 via npm first, so the CLAUDE.md instructions currently
don’t match the repo’s actual setup.

Code

CLAUDE.md[R29-37]

+Lint (all must pass — CI runs each):

-1. Open this repo in Claude Code (or your preferred AI assistant).
-2. Run `/init` — the assistant will read the repo, incorporate the description
-   above, and replace this seed with a complete `CLAUDE.md`.
-3. Commit the result.
+```bash
+uv run black --check tensor tests
+uv run isort --check-only tensor tests
+uv run flake8 tensor tests
+uv run bandit -c pyproject.toml -r tensor
+markdownlint-cli2 "**/*.md" "#node_modules" "#.local" "#.claude/skills" "#.teken"
+```

Evidence

CLAUDE.md directs running markdownlint-cli2 directly, but the workflow shows CI must install it via
npm first and the Python dev dependency set does not include it, so the documented local lint
sequence is incomplete.

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

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` tells readers to run `markdownlint-cli2 ...` as part of the lint suite, but it omits any install step. On a fresh machine this will fail because `markdownlint-cli2` is not provided by the Python environment.

## Issue Context
CI explicitly installs `markdownlint-cli2` with npm before running it. The local instructions should either (a) include the same npm install step (ideally pinned to the CI version), or (b) use an invocation that bootstraps it (e.g., `npx`), or (c) clearly note it’s an external prerequisite.

## Fix Focus Areas
- CLAUDE.md[29-37]

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

---

3. Explain test guarantee overstated ✓ Resolved 🐞 Bug ⚙ Maintainability

Description

CLAUDE.md claims test_every_catalog_path_resolves enforces that every new noun/verb has a matching
explain-catalog entry, but the test only iterates over existing catalog keys. This can lead to
missing explain entries slipping in while contributors believe the test would catch them.

Code

CLAUDE.md[R79-82]

+- **Explain catalog (`tensor/explain/`)** — `tensor/explain/catalog.py` is a
+  `dict[tuple[str,...], str]` of verbatim markdown keyed by command path;
+  `resolve()` looks it up or raises `CliError`. Every noun/verb you add must get
+  a matching catalog entry — `test_every_catalog_path_resolves` walks all keys.

Evidence

The doc claims the test enforces command-to-catalog completeness, but the test loops over
known_paths() and known_paths() is derived from ENTRIES.keys(), so commands absent from the
catalog are never checked.

CLAUDE.md[79-82]
tests/test_cli.py[111-115]
tensor/explain/init.py[12-25]

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` currently implies `test_every_catalog_path_resolves` will catch missing explain entries for newly added commands, but the test only validates that already-listed catalog keys resolve.

## Issue Context
Either update the documentation to describe the test accurately (recommended, minimal), or add additional test coverage that enumerates registered CLI commands and asserts each has a catalog entry.

## Fix Focus Areas
- CLAUDE.md[79-82]

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

---

[qodo-code-review]

PR Summary by Qodo

Docs: replace seed CLAUDE.md with full runtime guide (bump 0.2.1)
📝 Documentation ⚙️ Configuration changes 🕐 10-20 Minutes

Walkthroughs

Description

• Replace the bootstrap seed CLAUDE.md with a complete runtime guide for Claude Code.
• Document the CLI’s core contracts (register/dispatch, CliError, stdout/stderr split, --json).
• Bump project version to 0.2.1 and record the change in the changelog.

Diagram

graph TD
  A["Claude Code / dev"] -->|"reads"| B["CLAUDE.md"] -->|"documents"| C["CLI contracts"]
  C -->|"version & scripts"| D["pyproject.toml"] -->|"defines"| F["console cmd: tensor"]
  C -->|"release note"| E["CHANGELOG.md"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Align executable name with docs (rename script to tensor-cli)

• ➕ Removes the console-script mismatch; README examples would work as written
• ➕ Reduces user confusion around tensor vs tensor-cli
• ➖ Breaking change for existing users relying on tensor
• ➖ May require additional compatibility/wrapper scripting and release communication

2. Update README examples to use `tensor`

• ➕ Fixes user-facing quickstart immediately without breaking the installed command
• ➕ Keeps the distribution name (tensor-cli) while documenting the runtime executable accurately
• ➖ This PR intentionally chose to flag, not change, the mismatch; updating README may be considered scope creep
• ➖ Doesn’t address why prog/docs prefer tensor-cli while entrypoint is tensor

Recommendation: Current approach (documenting the mismatch clearly in CLAUDE.md) is appropriate for a docs-focused PR and avoids a potentially breaking CLI rename. Consider a follow-up PR/issue to either (a) update README examples to uv run tensor … or (b) add an additional tensor-cli console script for backward/forward compatibility if the project wants both names.

File Changes

Documentation (2)

CHANGELOG.md Add 0.2.1 entry describing CLAUDE.md expansion +6/-0

Add 0.2.1 entry describing CLAUDE.md expansion

• Adds a 0.2.1 release section documenting the '/init'-driven expansion of 'CLAUDE.md' into a full runtime guide and summarizing the key conventions captured there.

CHANGELOG.md

---

CLAUDE.md Replace bootstrap seed with full runtime guide and repo conventions +140/-19

Replace bootstrap seed with full runtime guide and repo conventions

• Rewrites 'CLAUDE.md' from a placeholder seed into a detailed runtime guide covering the repo’s current template status, CLI architecture/dispatch model, error/output/'--json' contracts, and the agent-first rubric expectations. Also documents operational conventions (version bumping, SonarCloud coverage setup, skill-kit rules) and highlights the console-script name mismatch ('tensor' vs 'tensor-cli').

CLAUDE.md

---

Other (1)

pyproject.toml Bump project version to 0.2.1 +1/-1

Bump project version to 0.2.1

• Updates the '[project]' version field from 0.2.0 to 0.2.1.

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

[OriNachum]

Addressed both doc findings in commit 799620e:

• docs: expand CLAUDE.md from seed into full runtime guide #2 markdownlint setup — added a note that markdownlint-cli2 is a Node tool outside the uv dev group (CI pins npm install -g markdownlint-cli2@0.21.0); the other four linters come from uv sync. Good catch.
• Add eidetic remember/recall memory skills #3 explain-test scope — corrected the claim: test_every_catalog_path_resolves only asserts that existing catalog keys resolve; it does not enforce that every registered command has an entry. Only the rubric's explain_self (root command) is CI-enforced. Reworded to call out the coverage gap.

(Finding #1, alignment delta, replied to on its inline thread.)

• tensor-cli (Claude)