katvan 0.2.4__tar.gz → 0.2.6__tar.gz

{katvan-0.2.4 → katvan-0.2.6}/.github/workflows/reference-sync.yml

@@ -34,11 +34,21 @@ jobs:
       - name: Pull reference
         run: katvan pull --all --json | tee /tmp/pull.json
 
+      - name: Clone agex-cli for SKILL.md sync
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          repository: agentculture/agex-cli
+          ref: main
+          path: _agex-cli-src
+
+      - name: Render agex commands from SKILL.md
+        run: python3 scripts/sync_agex_skills.py _agex-cli-src
+
       - name: Open PR if anything changed
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
-          if [ -z "$(git status --porcelain site/docs)" ]; then
+          if [ -z "$(git status --porcelain site/)" ]; then
             echo "No reference changes."
             exit 0
           fi
@@ -46,7 +56,7 @@ jobs:
           git checkout -b "$BRANCH"
           git config user.name "katvan-bot"
           git config user.email "katvan-bot@users.noreply.github.com"
-          git add site/docs
+          git add site/
           git commit -m "chore(reference): nightly sync $(date -u +%Y-%m-%d)"
           git push origin "$BRANCH"
           gh pr create \

{katvan-0.2.4 → katvan-0.2.6}/CHANGELOG.md

@@ -9,6 +9,40 @@ artifacts.
 
 ## [Unreleased]
 
+## [0.2.6] — 2026-05-18
+
+### Fixed
+
+- `katvan/cli/_commands/doctor.py`: extract `"index.md"` literal into a
+  module-level `_INDEX_MD` constant. Resolves SonarCloud's
+  duplicate-literal finding on the `_check_index` + `_check_reference`
+  pair landed in 0.2.5.
+
+## [0.2.5] — 2026-05-18
+
+### Added
+
+- Site: absorbed `agex-cli`'s standalone Jekyll docs site into
+  katvan. `culture.dev/agex/` is now served from katvan's main
+  build as plain paths inside the same site — no separate
+  `_config.agex.yml`, no separate Cloudflare project, no path-
+  routing rule. Prose pages (`/agex/`, `/agex/getting-started/`,
+  `/agex/skill-sources/`) are hand-imported; per-command pages
+  under `/agex/commands/<verb>/` are rendered from
+  `agex-cli/src/agent_experience/commands/*/SKILL.md` by
+  `scripts/sync_agex_skills.py`, refreshed by the nightly
+  `reference-sync.yml` cron.
+- `scripts/sync_agex_skills.py` + `tests/unit/test_sync_agex_skills.py`
+  (11 tests, stdlib-only renderer).
+- `tests/conftest.py` adds `scripts/` to `sys.path` so non-package
+  script modules are importable from unit tests.
+
+### Removed
+
+- `site/docs/agex-cli/index.md` (the marketing-rebuild placeholder
+  overview); inbound internal links repointed to `/agex/`. No
+  redirect — this is a renovation, not a migration.
+
 ## [0.2.4] — 2026-05-18
 
 ### Fixed

{katvan-0.2.4 → katvan-0.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: katvan
-Version: 0.2.4
+Version: 0.2.6
 Summary: Maintain sibling-repo docs under one roof on the culture.dev site.
 Project-URL: Homepage, https://github.com/agentculture/katvan
 Project-URL: Issues, https://github.com/agentculture/katvan/issues

katvan-0.2.6/docs/superpowers/specs/2026-05-18-agex-docs-absorption-design.md

@@ -0,0 +1,113 @@
+# agex docs absorption — design
+
+> Status: design (2026-05-18). Implementation plan follows in a separate doc under `docs/superpowers/plans/`.
+
+## Context
+
+`agentculture/agex-cli` ships a small Jekyll docs site that publishes to `culture.dev/agex/` from its own `docs/` folder via a standalone Cloudflare Pages project (`agex.pages.dev`) routed under `culture.dev`. Issue [#13](https://github.com/agentculture/katvan/issues/13) asked katvan to absorb that site so culture.dev is served end-to-end from a single source.
+
+The absorption advances the **operating model** for culture.dev. The repo name comes from Hebrew *katvan* — "writer / scribe". katvan owns the customer-facing site for the AgentCulture mesh:
+
+- **Sibling repos and their PMs / agents** know *what* changed in their product: the new verb, the shipped feature, the API rename, the deprecation. They file issues against katvan describing the substance.
+- **katvan** knows *how* that change should sit on a public site: where it goes in the IA, how the framing reads, what links in, what gets retired. katvan iterates `culture.dev`.
+
+Sibling repos do not run their own Jekyll deploys. They write the substance; katvan writes the page. This split is what makes a unified marketing/docs surface possible without each product team needing to think about navigation or voice.
+
+## Goal
+
+After this PR ships:
+
+- `culture.dev/agex/` and all subpaths are served from katvan's existing Cloudflare deployment as plain paths inside the main Jekyll build. No subsite scaffolding, no per-project Cloudflare project, no path-routing rule, no redirects.
+- The published per-command pages stay in sync with the canonical `SKILL.md` files inside agex-cli (the CLI ships those, and they are the same files `agex learn --json` / `agex explain --json` serve to agents). Drift between site and CLI is impossible by construction (rendering is automated; no hand-authored copy).
+- agex-cli no longer needs `docs/`, the docs deploy workflow, or its render script. (Phase 2, separate PR; see Cutover.)
+
+## Non-goals
+
+- Visual / design uplift for `/agex/` pages. Folded into katvan's existing dark overlay; richer treatment parked in [#14](https://github.com/agentculture/katvan/issues/14).
+- Migrating other subsites (`/afi/`, `/agentirc/`, `/citation-cli/`). Each gets its own absorption PR when a sibling-repo issue requests it.
+- Rewriting `docs/architecture/subsites.md`. The doc still describes the (now-receding) "separate Cloudflare project per subsite" pattern. One link inside it is fixed in this PR; the broader rewrite is a follow-up.
+- Parity verification against the existing agex.pages.dev rendering. This is a renovation, not a faithful migration; modest content / style drift is acceptable.
+
+## URL structure
+
+Single-build, single-deployment. `/agex/` is a path node inside `culture.dev`, with sub-pages.
+
+| URL | Source file in katvan | Origin |
+|---|---|---|
+| `/agex/` | `site/agex/index.md` | wholesale from `agex-cli/docs/index.md` |
+| `/agex/getting-started/` | `site/agex/getting-started.md` | wholesale from `agex-cli/docs/getting-started.md` |
+| `/agex/skill-sources/` | `site/agex/skill-sources.md` | wholesale from `agex-cli/docs/skill-sources.md` |
+| `/agex/commands/` | `site/agex/commands/index.md` | generated by sync script |
+| `/agex/commands/<verb>/` | `site/agex/commands/<verb>.md` × 7 | generated from `agex-cli/src/agent_experience/commands/<verb>/SKILL.md` |
+| `/agex-cli/` | (deleted) | replaced by content under `/agex/` |
+
+`site/docs/agex-cli/index.md` is removed. Its two internal inbound links (`site/docs/antoine/index.md:21`, `site/docs/architecture/subsites.md:108`) are rewritten to `/agex/`.
+
+## SKILL.md sync mechanism
+
+**Script:** new `scripts/sync_agex_skills.py` in katvan. Reads SKILL.md files from a given agex-cli checkout path, strips each SKILL.md's own YAML frontmatter, prepends a Jekyll-friendly frontmatter (`title`, `parent: Commands`, `nav_order: order*10`), and writes the result into `site/agex/commands/<verb>.md`. Maintains the `_clear_stale_pages` invariant (removed-upstream commands disappear locally too). Stdlib only — no dependency on the `agent_experience` Python package.
+
+The script is owned by katvan (single source of truth for the render shape). agex-cli's existing `scripts/sync_skill_md.py` is retired in Phase 2.
+
+**Invocation:** `python3 scripts/sync_agex_skills.py <agex-cli-checkout-path>`. The reference-sync workflow passes the path of a freshly-cloned `agentculture/agex-cli@main`.
+
+## Reference-sync workflow integration
+
+The existing `.github/workflows/reference-sync.yml` (nightly cron + manual `workflow_dispatch`) currently runs `katvan pull --all` for AFI references and opens a PR if `site/docs` changed. Extend it:
+
+1. After the `katvan pull --all` step, check out `agentculture/agex-cli@main` into `_agex-cli-src/`.
+2. Run `python3 scripts/sync_agex_skills.py _agex-cli-src`.
+3. Broaden the "Open PR if anything changed" trigger from `site/docs` to `site/`.
+
+PR title and body wording stay the same (`chore(reference): nightly sync YYYY-MM-DD`); the diff itself reveals whether AFI refs, agex commands, or both moved.
+
+Rendered output is **committed in katvan**. PR builds are deterministic from the committed state. Drift between agex-cli `SKILL.md` and the site is bounded at 24 hours (cron cadence). A maintainer can fire the workflow on demand after a notable agex-cli change to shrink that window.
+
+## Cutover
+
+**Phase 1 — this PR.** Add `site/agex/*` content (including a one-time hand-run of `sync_agex_skills.py` so `commands/*.md` is populated immediately, not deferred to the first cron). Delete `site/docs/agex-cli/index.md` and update its two inbound links. Add the agex render steps to `reference-sync.yml`. Drop the `/agex/`-exclusion from `site/sitemap-main.html` and the `/agex/sitemap.xml` entry from `site/sitemap.html`. Version bump + CHANGELOG. htmlproofer hard-gate (live from PR #28) catches link regressions on its own — no new CI step needed.
+
+On merge, katvan's existing deployment starts serving `culture.dev/agex/*`. The standalone `agex.pages.dev` deployment still builds on agex-cli pushes but its content is no longer reached.
+
+**Phase 2 — follow-up PR on `agentculture/agex-cli`.** Delete `docs/`, `.github/workflows/docs.yml`, `scripts/sync_skill_md.py`. Keep `src/agent_experience/commands/*/SKILL.md` — that's the source of truth katvan now pulls from. The `agex` Cloudflare Pages project becomes dead weight; the cloudflare team retires it at their convenience.
+
+katvan files one follow-up issue on `agentculture/agex-cli` (via `agtag`) immediately after Phase 1 merges, referencing this PR. No rollback plan — fix-forward.
+
+## Files touched in katvan
+
+**Add (12 files)**
+- `scripts/sync_agex_skills.py`
+- `site/agex/index.md`, `site/agex/getting-started.md`, `site/agex/skill-sources.md`
+- `site/agex/commands/index.md`
+- `site/agex/commands/{doctor,explain,gamify,hook,learn,overview,pr}.md` (7)
+
+**Modify**
+- `site/sitemap-main.html` — drop the `if page.url contains "/agex/"` skip
+- `site/sitemap.html` — drop the `<sitemap><loc>{{ '/agex/sitemap.xml' | absolute_url }}</loc></sitemap>` line
+- `site/docs/antoine/index.md` — rewrite `[agex-cli](/agex-cli/)` → `[agex](/agex/)` at line 21
+- `site/docs/architecture/subsites.md` — rewrite `[`agex-cli`](/agex-cli/)` at line 108 to point at `/agex/`
+- `.github/workflows/reference-sync.yml` — add the agex-cli checkout + render steps; broaden the PR trigger from `site/docs` to `site/`
+- `pyproject.toml` — version bump
+- `CHANGELOG.md` — entry under Unreleased
+
+**Delete**
+- `site/docs/agex-cli/index.md`
+
+## Verification
+
+**Local pre-PR**
+1. `python3 scripts/sync_agex_skills.py /home/spark/git/agex-cli` — confirm 8 files written under `site/agex/commands/` (7 verbs + 1 `index.md`).
+2. `bundle exec jekyll build --config _config.base.yml,_config.culture.yml -d _site_culture --strict_front_matter` — clean.
+3. `htmlproofer _site_culture --disable-external --allow-hash-href` — 0 failures.
+4. Spot-check `_site_culture/agex/index.html`, `_site_culture/agex/getting-started/index.html`, `_site_culture/agex/commands/pr/index.html`. Confirm: page titles render, sidebar shows the command list, internal links resolve, no `404`s on `/agex/*`.
+5. Spot-check `_site_culture/sitemap-main.xml` includes `/agex/`, `/agex/getting-started/`, `/agex/commands/pr/` entries. `_site_culture/sitemap.xml` no longer references `/agex/sitemap.xml`.
+
+**CI gates (existing)**
+- `build-docs` workflow: Jekyll `--strict_front_matter` + htmlproofer hard-fail
+- `version-check`
+- `SonarCloud Code Analysis`
+- Cloudflare Pages preview deploys for visual review
+
+**Post-merge**
+- Manual trigger of `reference-sync.yml` confirms the cron path works end-to-end (clones agex-cli, renders, opens PR only if content moved).
+- Follow-up issue filed against `agentculture/agex-cli` for Phase 2 (Jekyll teardown).

{katvan-0.2.4 → katvan-0.2.6}/katvan/cli/_commands/doctor.py

@@ -15,6 +15,8 @@ from pathlib import Path
 from katvan import repos
 from katvan.cli._output import emit_result
 
+_INDEX_MD = "index.md"
+
 
 def register(sub: argparse._SubParsersAction) -> None:
     parser = sub.add_parser("doctor", help="check culture.dev IA health")
@@ -23,20 +25,30 @@ def register(sub: argparse._SubParsersAction) -> None:
 
 
 def _check_index(site_root: Path, entry: dict) -> str | None:
-    page = site_root / "docs" / entry["id"] / "index.md"
+    site_path = entry.get("site_path")
+    if site_path:
+        rel = site_path.strip("/")
+        page = site_root / rel / _INDEX_MD
+        rel_display = f"site/{rel}/{_INDEX_MD}"
+    else:
+        page = site_root / "docs" / entry["id"] / _INDEX_MD
+        rel_display = f"site/docs/{entry['id']}/{_INDEX_MD}"
     if not page.is_file():
-        return f"missing site/docs/{entry['id']}/index.md (hand-authored page)"
+        return f"missing {rel_display} (hand-authored page)"
     if not page.read_text().strip():
-        return f"site/docs/{entry['id']}/index.md is empty"
+        return f"{rel_display} is empty"
     return None
 
 
 def _check_reference(site_root: Path, entry: dict) -> str | None:
     if entry.get("docs_mode") != "pull-reference":
         return None
-    ref = site_root / "docs" / entry["id"] / "reference" / "index.md"
+    ref = site_root / "docs" / entry["id"] / "reference" / _INDEX_MD
     if not ref.is_file():
-        return f"missing site/docs/{entry['id']}/reference/index.md (run `katvan pull {entry['id']}`)"
+        return (
+            f"missing site/docs/{entry['id']}/reference/{_INDEX_MD} "
+            f"(run `katvan pull {entry['id']}`)"
+        )
     return None
 
 
@@ -45,7 +57,11 @@ def _check_readme_link(entry: dict) -> str | None:
     readme = sibling / "README.md"
     if not readme.is_file():
         return None
-    expected = f"https://culture.dev/{entry['id']}/"
+    site_path = entry.get("site_path")
+    if site_path:
+        expected = f"https://culture.dev{site_path}"
+    else:
+        expected = f"https://culture.dev/{entry['id']}/"
     if expected not in readme.read_text():
         return f"warning: {sibling}/README.md missing link to {expected}"
     return None

{katvan-0.2.4 → katvan-0.2.6}/katvan/repos.py

@@ -184,7 +184,7 @@ def repos() -> Iterator[tuple[str, str, str]]:
 # and the overview verb does not need them.
 _SCALAR_FIELDS: tuple[str, ...] = (
     "category", "maturity", "docs_mode", "description",
-    "package", "binary", "docs", "install", "caveat",
+    "package", "binary", "docs", "site_path", "install", "caveat",
 )
 
 

{katvan-0.2.4 → katvan-0.2.6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "katvan"
-version = "0.2.4"
+version = "0.2.6"
 description = "Maintain sibling-repo docs under one roof on the culture.dev site."
 readme = "README.md"
 license = "MIT"

katvan-0.2.6/scripts/sync_agex_skills.py

@@ -0,0 +1,133 @@
+#!/usr/bin/env python3
+"""sync_agex_skills.py — render agex-cli SKILL.md files into katvan site pages.
+
+Usage:
+    python3 scripts/sync_agex_skills.py <path-to-agex-cli-checkout>
+
+Reads ``<agex-cli>/src/agent_experience/commands/*/SKILL.md``, strips each
+SKILL.md's own YAML frontmatter, prepends a Jekyll-friendly frontmatter
+pointing at the ``Commands`` parent page, and writes the result to
+``site/agex/commands/<verb>.md``. Also writes the ``Commands`` index page.
+
+Deterministic by construction:
+  * Inputs are sorted alphabetically (so nav order is stable).
+  * Removed-upstream commands are deleted locally on re-run
+    (``_clear_stale_pages``).
+  * Re-running on unchanged input produces byte-identical output (CI relies
+    on this so bot-PR diffs stay minimal).
+
+stdlib only — no dependency on the ``agent_experience`` Python package or
+PyYAML. The frontmatter shape we read is small enough for a hand parse.
+"""
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+DEFAULT_OUT_DIR = REPO_ROOT / "site" / "agex" / "commands"
+
+_JEKYLL_FRONTMATTER = (
+    "---\n"
+    "title: {title}\n"
+    "parent: Commands\n"
+    "nav_order: {order}\n"
+    "sites: [culture]\n"
+    "permalink: /agex/commands/{name}/\n"
+    "---\n\n"
+)
+
+_INDEX_PAGE = (
+    "---\n"
+    "title: Commands\n"
+    "has_children: true\n"
+    "nav_order: 3\n"
+    "sites: [culture]\n"
+    "permalink: /agex/commands/\n"
+    "---\n\n"
+    "# Commands\n\n"
+    "Auto-imported from `agex-cli/src/agent_experience/commands/*/SKILL.md`"
+    " by `scripts/sync_agex_skills.py`. Re-run via the nightly"
+    " `reference-sync.yml` workflow or fire `workflow_dispatch` manually"
+    " after a notable agex-cli change.\n"
+)
+
+_NAME_RE = re.compile(r"^name:\s*(.+?)\s*$", re.MULTILINE)
+
+
+def parse_skill_md(text: str) -> tuple[str, str]:
+    """Return (name, body) from a SKILL.md file.
+
+    SKILL.md format: ``---\\n<yaml>\\n---\\n\\n<body>``. We extract the
+    ``name:`` field from the YAML block and return everything after the
+    closing fence (byte-for-byte).
+    """
+    if not text.startswith("---\n"):
+        raise ValueError("SKILL.md missing opening frontmatter fence")
+    end = text.find("\n---\n", 4)
+    if end == -1:
+        raise ValueError("SKILL.md missing closing frontmatter fence")
+    frontmatter = text[4:end]
+    body = text[end + 5:]
+    if body.startswith("\n"):
+        body = body[1:]
+    match = _NAME_RE.search(frontmatter)
+    if not match:
+        raise ValueError("SKILL.md frontmatter missing `name:` field")
+    return match.group(1), body
+
+
+def _commands_dir(agex_root: Path) -> Path:
+    return agex_root / "src" / "agent_experience" / "commands"
+
+
+def _top_level_skill_md(agex_root: Path) -> list[Path]:
+    """Return alphabetical SKILL.md paths for the top-level command dirs."""
+    cmds = _commands_dir(agex_root)
+    return sorted(
+        cmd_dir / "SKILL.md"
+        for cmd_dir in cmds.iterdir()
+        if cmd_dir.is_dir() and (cmd_dir / "SKILL.md").is_file()
+    )
+
+
+def _clear_stale_pages(out_dir: Path, expected: set[str]) -> None:
+    """Remove out_dir/*.md not in ``expected``. Always re-writes index.md."""
+    if not out_dir.exists():
+        return
+    for path in sorted(out_dir.glob("*.md")):
+        if path.name in expected:
+            continue
+        path.unlink()
+
+
+def render(agex_root: Path, out_dir: Path = DEFAULT_OUT_DIR) -> int:
+    """Render all top-level SKILL.md files under agex_root into out_dir."""
+    out_dir.mkdir(parents=True, exist_ok=True)
+    skills = _top_level_skill_md(agex_root)
+    expected = {f"{p.parent.name}.md" for p in skills} | {"index.md"}
+    _clear_stale_pages(out_dir, expected)
+    for order, skill_md in enumerate(skills, start=1):
+        slug = skill_md.parent.name
+        title, body = parse_skill_md(skill_md.read_text(encoding="utf-8"))
+        page = _JEKYLL_FRONTMATTER.format(
+            title=title, order=order * 10, name=slug
+        ) + body
+        (out_dir / f"{slug}.md").write_text(page, encoding="utf-8")
+    (out_dir / "index.md").write_text(_INDEX_PAGE, encoding="utf-8")
+    return 0
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) != 2:
+        print(
+            "usage: sync_agex_skills.py <agex-cli-checkout-path>",
+            file=sys.stderr,
+        )
+        return 2
+    return render(Path(argv[1]).resolve())
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv))

{katvan-0.2.4 → katvan-0.2.6}/site/_data/agentculture_repos.yml

@@ -20,6 +20,11 @@
 #   package      (optional) PyPI package name if applicable
 #   binary       (optional) CLI binary name if applicable
 #   docs         (optional) absolute URL — culture.dev page or repo README
+#   site_path    (optional) the canonical katvan-site path for this repo,
+#                  if it differs from `/<id>/`. Set this when a repo's
+#                  docs live under a different slug (e.g. `agex-cli`'s
+#                  docs live at `/agex/`). Templates fall back to
+#                  `/<id>/` when this is unset.
 #   install      (optional) one-line install command
 #   caveat       (optional) one short sentence — a current public-facing
 #                  limitation a reader should know about
@@ -77,6 +82,7 @@
   description: Improve an agent's developer experience; powers `culture devex`.
   binary: agex
   docs: https://culture.dev/agex/
+  site_path: /agex/
   caveat: "Reference sync deferred — `agex learn` does not yet support `--json`."
   related: [culture]
 

{katvan-0.2.4 → katvan-0.2.6}/site/_layouts/home.html

@@ -30,7 +30,8 @@ layout: default
         <h3>{{ cat | replace: "-", " " | capitalize }}</h3>
         <ul>
         {% for r in repos_in_cat %}
-          <li><a href="/{{ r.id }}/">{{ r.id }}</a> — {{ r.description }}</li>
+          {% if r.site_path %}{% assign r_path = r.site_path %}{% else %}{% assign r_path = r.id | prepend: "/" | append: "/" %}{% endif %}
+          <li><a href="{{ r_path }}">{{ r.id }}</a> — {{ r.description }}</li>
         {% endfor %}
         </ul>
       </article>

katvan-0.2.6/site/agex/commands/doctor.md

@@ -0,0 +1,43 @@
+---
+title: doctor
+parent: Commands
+nav_order: 10
+sites: [culture]
+permalink: /agex/commands/doctor/
+---
+
+# `agex doctor`
+
+Run a zero-argument health check across:
+
+1. **Install** — `agex` version, Python version, package resources are reachable.
+2. **Project state** — whether `.agex/` exists in the current directory; if it does, that `config.toml` parses, `.gitignore` matches the managed content, and `data/` is writable.
+3. **Internal consistency** — every shipped `commands/*/SKILL.md` parses with the required frontmatter, every per-backend capability YAML loads.
+4. **Operator verification** — a short markdown checklist of things `doctor` cannot verify automatically (network reach, git-tracking of `.agex/config.toml`, agent shell-tool wiring).
+
+`doctor` is strictly read-only. It will never create `.agex/` or write anywhere on disk — if the directory is missing, that is reported as info and the command keeps going.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | All checks `ok`, possibly with `warn` rows. |
+| `1` | At least one `fail` row. Stderr carries a one-line summary. |
+| `2` | CLI usage error (e.g., unknown role passed via `--role`). |
+
+## From your shell tool
+
+```bash
+agex doctor                       # base health check
+agex doctor --role pr-review      # base + role-specific checks (when a role file ships)
+```
+
+## Role-specific checks
+
+`doctor` has an extension hook: a role file at `commands/doctor/assets/roles/<role>.md.j2` (slug-validated, `^[a-z][a-z0-9-]*$`) is rendered as an extra section when the user passes `--role <role>`. The current release ships zero role files — the contract exists so role-specific diagnostics can be added without touching `doctor` itself.
+
+## What `doctor` does *not* do
+
+- It does not run backend probes — that's `agex overview --agent X`.
+- It does not perform any auto-fix. Recovery instructions are emitted as markdown for the operator (agent or human) to act on.
+- It does not touch the network.

katvan-0.2.6/site/agex/commands/explain.md

@@ -0,0 +1,28 @@
+---
+title: explain
+parent: Commands
+nav_order: 20
+sites: [culture]
+permalink: /agex/commands/explain/
+---
+
+# `agex explain <topic>`
+
+Use this to get authoritative, deterministic documentation on an agex command, lesson, or concept without invoking a lesson or running a probe.
+
+## How it resolves
+
+1. `commands/<topic>/SKILL.md` (command-level, wins if present)
+2. `commands/learn/assets/topics/<topic>/SKILL.md` (lesson-level)
+3. `commands/explain/assets/topics/<topic>.md` (concept-level override)
+
+First match wins.
+
+## From your shell tool
+
+```bash
+agex explain overview
+agex explain gamify
+agex explain levelup
+agex explain agex          # self-describing page
+```

katvan-0.2.6/site/agex/commands/gamify.md

@@ -0,0 +1,33 @@
+---
+title: gamify
+parent: Commands
+nav_order: 30
+sites: [culture]
+permalink: /agex/commands/gamify/
+---
+
+# `agex gamify --agent <backend>` / `agex gamify --uninstall --agent <backend>`
+
+## What it does
+
+Writes backend-native hook fragments (each tagged with a stable `agex:*` ID) that call `agex hook write <event>` on PostToolUse, UserPromptSubmit, and Stop events. Agent-authored skills (e.g., `levelup`) read the accumulated data via `agex hook read`.
+
+## Why it's safe
+
+- Idempotent: re-running is a no-op.
+- Reversible: `--uninstall` removes exactly the `agex:*` fragments; user-authored hooks are untouched.
+- Calling `agex gamify` explicitly is the confirmation — no separate prompt.
+
+## Unsupported backends
+
+If your backend doesn't support hooks, you get a markdown notice + issue link instead.
+
+## From your shell tool
+
+```bash
+agex gamify --agent claude-code
+# ... use your runtime for a while ...
+agex hook read --agent claude-code
+# ... later, to undo:
+agex gamify --uninstall --agent claude-code
+```

katvan-0.2.6/site/agex/commands/hook.md

@@ -0,0 +1,33 @@
+---
+title: hook
+parent: Commands
+nav_order: 40
+sites: [culture]
+permalink: /agex/commands/hook/
+---
+
+# `agex hook write <event> [key=value ...]` / `agex hook read --agent <backend>`
+
+## `write`
+
+Called by installed hooks (see `agex gamify`, Phase 7). Appends a JSON line to `.agex/data/<event>.json`. Silent. Safe for concurrent invocation (file locking via `portalocker`).
+
+```bash
+agex hook write post-tool-use tool=Read
+```
+
+## `read`
+
+Renders tracked events as a markdown table. Prints the source JSON path for deeper inspection.
+
+```bash
+agex hook read --agent claude-code
+```
+
+## Notes
+
+- Event names are free-form; conventional names: `post-tool-use`, `user-prompt`, `stop`, `sessions`.
+- Extra positional `key=value` pairs are captured into the payload. Empty keys (e.g., `=foo`) are dropped.
+- Timestamp (`ts`) is attached automatically; a positional `ts=<value>` overrides it (useful for replays).
+- The positional `<event>` name is authoritative — it always wins over any `event=...` pair in args.
+- Malformed JSON lines in `.agex/data/*.json` (e.g., from a partial write) are skipped with a warning on `hook read`, not raised.

katvan-0.2.6/site/agex/commands/index.md

@@ -0,0 +1,11 @@
+---
+title: Commands
+has_children: true
+nav_order: 3
+sites: [culture]
+permalink: /agex/commands/
+---
+
+# Commands
+
+Auto-imported from `agex-cli/src/agent_experience/commands/*/SKILL.md` by `scripts/sync_agex_skills.py`. Re-run via the nightly `reference-sync.yml` workflow or fire `workflow_dispatch` manually after a notable agex-cli change.

katvan-0.2.6/site/agex/commands/learn.md

@@ -0,0 +1,23 @@
+---
+title: learn
+parent: Commands
+nav_order: 50
+sites: [culture]
+permalink: /agex/commands/learn/
+---
+
+# `agex learn [topic] --agent <backend>`
+
+Without a topic, lists the lessons available for your backend. With a topic, teaches it — emits a markdown lesson body plus inline skill-template code blocks you can write into your project.
+
+## From your shell tool
+
+```bash
+agex learn --agent claude-code
+agex learn introspect --agent claude-code
+```
+
+## Notes
+
+- Lessons gated on a backend feature (e.g., `gamify` needs hooks) may still appear in the list, but they are not currently annotated as unsupported in the menu — Phase 8 adds that capability-based routing.
+- v0.1 emits inline code blocks only. A future `--write` flag is tracked as an open issue.

katvan-0.2.6/site/agex/commands/overview.md

@@ -0,0 +1,33 @@
+---
+title: overview
+parent: Commands
+nav_order: 60
+sites: [culture]
+permalink: /agex/commands/overview/
+---
+
+# `agex overview --agent <backend>`
+
+Call this to get a read-only markdown snapshot of what's configured in the
+current project for a given backend — skills, hooks, agents, MCP servers,
+and relevant config files. Descriptive, not diagnostic. Read it before you
+act.
+
+## From your shell tool
+
+```bash
+agex overview --agent claude-code
+agex overview --agent codex
+```
+
+## What you get
+
+Markdown sections: Project root, `CLAUDE.md`/`AGENTS.md` presence, Skills,
+Hooks, MCP servers, Settings.
+
+## Notes
+
+- Malformed files are skipped with a `> ⚠️` inline warning.
+- Read-only except first-run `.agex/` init.
+- Build diagnostic logic (gaps, recommendations) into an agent-authored skill:
+  `agex learn introspect --agent <backend>`.