fix: resolve explain webglass + re-init CLAUDE.md from seed

[OriNachum]

What

Two changes, both stemming from running /init against issue #2:

1. Fix the red rubric gate. teken cli doctor . --strict (the CI lint job's "afi rubric gate" step) was exiting 1. Its explain_self check probes the import-package name webglass, but the explain catalog only keyed the dist name webglass-cli, so explain webglass 404'd. Added the ("webglass",) root key in webglass/explain/catalog.py plus a regression test. The gate is green again.

2. Re-initialize CLAUDE.md from the bootstrap seed into a full runtime prompt. The repo was still carrying the culture-agent-template seed placeholder. The new CLAUDE.md documents the two-layer state the repo is actually in — the template's agent-first CLI skeleton that ships today vs. the not-yet-built WebGlass product (Playwright + Chromium, token-budgeted extraction, Web-memory, exploration paths, citations) described in issue Design WebGlass: agent web exploration with Playwright, Chromium, and Web-memory #2 — plus the CLI registration/error/output/explain contracts, the agent-first rubric-gate constraints, mesh identity (backend: colleague → AGENTS.colleague.md), the version-bump/cicd conventions, and the target architecture to build toward.

Why

The rubric gate failing means CI's lint job is red on main today — the one-line catalog fix turns it green. The CLAUDE.md re-init is the deliverable of /init; it also captures two gotchas a future contributor will otherwise trip on: the console script is webglass (not webglass-cli, which the README's examples incorrectly use), and the dist/import/script/prog names diverge.

Testing

• uv run pytest -n auto — 23 passed, 92.6% coverage (was 22; +1 regression test for explain webglass)
• uv run teken cli doctor . --strict — exit 0 (was exit 1)
• black --check / isort --check-only / flake8 / bandit — clean
• markdownlint-cli2 on CLAUDE.md + CHANGELOG.md — 0 errors

Notes

• This PR touches CLAUDE.md, which triggers the cicd alignment-delta rule, but workflow.sh delta (sibling-alignment dump) needs a per-machine .claude/skills.local.yaml that isn't present here, so it couldn't run. No sibling-prompt drift is expected — the change is local to this repo's identity/docs.
• Version bumped 0.4.0 → 0.4.1 (patch).

🤖 Generated with Claude Code

• webglass-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: 🎫 Design WebGlass: agent web exploration with Playwright, Chromium, and Web-memory

1. Rubric docs contradict fix ✓ Resolved 🐞 Bug ⚙ Maintainability

Description

CLAUDE.md still claims the rubric gate is currently RED/failing because the explain catalog lacks
the ("webglass",) root key, but this PR adds that key—so the guidance is now self-contradictory and
misleading for contributors diagnosing CI/rubric failures.

Code

CLAUDE.md[R122-129]

+- **`explain <self>`** must resolve (see the gotcha — this check is currently
+  failing and needs fixing).
+
+> ⚠️ **The rubric gate is currently RED.** `explain_self` probes
+> `explain webglass` (the import-package name), but the catalog's root key is
+> `("webglass-cli",)` only. Fix: add `("webglass",): _ROOT` to `ENTRIES` in
+> `webglass/explain/catalog.py`. Until then `teken cli doctor . --strict` exits
+> 1 and the lint job fails.

Evidence

CLAUDE.md explicitly says the catalog only has the ("webglass-cli",) root key and that adding
("webglass",) is required for the rubric gate, but the updated catalog already contains
("webglass",): _ROOT after this PR; therefore the doc is stale and contradictory.

CLAUDE.md[122-129]
CLAUDE.md[229-230]
webglass/explain/catalog.py[119-123]

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` still states that the rubric gate (`teken cli doctor . --strict`) is currently failing and instructs adding `("webglass",): _ROOT` to the explain catalog. This PR already adds that entry, so the doc is now incorrect and misleading.

### Issue Context
The PR fixes `explain webglass` by adding `("webglass",)` to `webglass/explain/catalog.py` and adds a regression test. The rubric section and the “Known gotchas” section in `CLAUDE.md` should be updated to reflect the fixed state.

### Fix Focus Areas
- CLAUDE.md[122-130]
- CLAUDE.md[221-230]
- webglass/explain/catalog.py[119-123]

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

---

2. Catalog docstring outdated ✓ Resolved 🐞 Bug ⚙ Maintainability

Description

webglass/explain/catalog.py’s module docstring says only () and ("webglass-cli",) resolve to the
root entry, but the PR adds ("webglass",) as an additional root alias, making the docstring
incorrect.

Code

webglass/explain/catalog.py[R119-123]

ENTRIES: dict[tuple[str, ...], str] = {
    (): _ROOT,
    ("webglass-cli",): _ROOT,
+    ("webglass",): _ROOT,
    ("whoami",): _WHOAMI,

Evidence

The docstring explicitly enumerates which keys resolve to the root entry, but the ENTRIES mapping
includes an additional root alias (("webglass",)) not documented there.

webglass/explain/catalog.py[1-5]
webglass/explain/catalog.py[119-123]

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 module docstring in `webglass/explain/catalog.py` describes the set of root aliases, but it no longer matches the updated `ENTRIES` mapping after adding the new `("webglass",)` alias.

### Issue Context
The docstring currently states only `()` and `("webglass-cli",)` map to `_ROOT`. The `ENTRIES` dict now also includes `("webglass",)`.

### Fix Focus Areas
- webglass/explain/catalog.py[1-5]
- webglass/explain/catalog.py[119-123]

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

---

[qodo-code-review]

PR Summary by Qodo

Fix explain webglass resolution and reinitialize CLAUDE.md prompt
🐞 Bug fix 🧪 Tests 📝 Documentation ⚙️ Configuration changes 🕐 20-40 Minutes

Description

• Add webglass root alias to explain catalog to satisfy rubric explain_self.
• Add regression test ensuring explain webglass succeeds.
• Replace seed CLAUDE.md with full runtime prompt; bump version to 0.4.1.

Diagram

graph TD
  CI{{"CI lint: teken doctor"}} --> MAIN["CLI entry (main)" ] --> EXPLAIN["explain command" ] --> CATALOG["catalog entries" ]
  TESTS["pytest" ] --> MAIN
  TESTS --> CATALOG
  DOCS["CLAUDE.md prompt" ] --> MAIN
  VER["pyproject version" ] --> MAIN
  subgraph Legend
    direction LR
    _ext{{"External/CI"}} ~~~ _svc["Runtime code" ] ~~~ _file["Repo file" ]
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Unify naming to remove aliases (dist/import/script/prog)

• ➕ Eliminates confusion between webglass-cli and webglass across help/docs/tests
• ➕ Reduces future need for compatibility aliases in explain/catalog
• ➖ Broader breaking-surface (help text, docs, rubric expectations, potential downstream consumers)
• ➖ Not a minimal fix for a currently-red CI gate

2. Teach `explain` to canonicalize known self-identifiers

• ➕ Centralizes aliasing logic (e.g., map webglass, webglass-cli to one canonical root)
• ➕ Avoids proliferating duplicate catalog keys over time
• ➖ More logic in the resolver path; harder to keep behavior obvious
• ➖ Still requires deciding which identifiers are supported and testing them

3. Adjust the rubric/tooling check to probe dist/prog name only

• ➕ Keeps catalog strictly keyed to the CLI’s presented name (webglass-cli)
• ➕ Avoids expanding public surface area of explain identifiers
• ➖ Requires changes outside this repo (teken/rubric), slower iteration
• ➖ Doesn’t help users who naturally try explain webglass based on import/script name

Recommendation: Keep the PR’s minimal alias-in-catalog fix: it’s the smallest change that unblocks CI and is easy to reason about. Consider a later, intentional naming-convergence effort (or centralized canonicalization) once the project moves beyond the template CLI skeleton into the real WebGlass verbs.

Files changed (5) +241 / -20

Bug fix (1) +1 / -0

catalog.pyAlias root explain entry for import-package name 'webglass' +1/-0

Alias root explain entry for import-package name 'webglass'

• Adds '("webglass",): _ROOT' so both the dist name ('webglass-cli') and import-package name ('webglass') resolve to the root explain entry. This fixes the CI rubric gate that probes 'explain webglass'.

webglass/explain/catalog.py

Tests (1) +8 / -0

test_cli.pyAdd regression test for 'explain webglass' alias +8/-0

Add regression test for 'explain webglass' alias

• Adds a test ensuring 'main(["explain", "webglass"])' returns 0 and emits markdown. Protects against future regressions that would re-break the rubric’s 'explain_self' probe.

tests/test_cli.py

Documentation (2) +231 / -19

CHANGELOG.mdAdd 0.4.1 changelog entry for explain fix and prompt re-init +10/-0

Add 0.4.1 changelog entry for explain fix and prompt re-init

• Documents the 0.4.1 release, including the 'explain webglass' resolution fix and the CLAUDE.md reinitialization. Records why the CI gate was failing and that a regression test was added.

CHANGELOG.md

CLAUDE.mdReplace bootstrap seed with full repo runtime prompt +221/-19

Replace bootstrap seed with full repo runtime prompt

• Replaces the template placeholder with a detailed operational prompt covering the current CLI skeleton, rubric-gate constraints, identity/mesh conventions, workflows, and the target WebGlass architecture described in issue #2. Calls out naming gotchas (dist/import/script/prog) and the required CI/lint commands.

CLAUDE.md

Other (1) +1 / -1

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

Bump project version to 0.4.1

• Updates the package version from 0.4.0 to 0.4.1 to satisfy the version-bump-per-PR CI gate and align with the changelog entry.

pyproject.toml

[OriNachum]

Triage of the Qodo review (both findings → FIX, pushed in 990fb40):

1. Rubric docs contradict fix (🐞 Bug, review-recommended) — valid, and self-inflicted: the CLAUDE.md re-init described the rubric gate as "currently RED" and told contributors to add ("webglass",): _ROOT, while the very same PR adds that key. Reframed the explain_self bullet as a standing requirement — the root entry must resolve under both the dist name (webglass-cli) and the import name (webglass, which is what the rubric probes) — and removed the stale "currently failing" gotcha, folding the dist-vs-import rationale into the naming gotcha instead.

2. Catalog docstring outdated (🐞 Bug, optional) — valid. webglass/explain/catalog.py's module docstring enumerated only () and ("webglass-cli",) as root aliases; updated it to include ("webglass",) with a note on why it exists.

Both are documentation-accuracy only — no behaviour change, so the PR stays at 0.4.1. Verified after the fix: teken cli doctor . --strict exit 0, 23 tests pass, black/isort/flake8/markdownlint clean.

• webglass-cli (Claude)