docs: governance page + slickness pass#14
Conversation
Substance + discoverability + the one place the aesthetic broke — all within
the technical-archive style.
New pages
- governance.md: capability-first — maps the six durable model-risk needs
(complete inventory, tiering, change control, lineage, validation records,
point-in-time) to model-ledger primitives. Regulations are a thin, current
layer (SR 26-2/OCC 2026-13 which superseded SR 11-7, EU AI Act Annex IV,
NIST AI RMF, ISO 42001) — update a profile, not the inventory.
- guides/cli.md: all eight verbs (the CLI card no longer dead-ends).
- installation.md: the extras matrix + Python 3.10+.
- glossary.md (+ includes/abbreviations.md auto-appended for site-wide
hover-tooltips on DataNode/Snapshot/Composite/etc.).
Slickness (style-preserving)
- Style the mkdocstrings API reference into the theme (serif headings,
hairline separators, oxblood symbol/label chips) — the one page that fell
back to default Material.
- Per-page "Copy as Markdown / View / Open in Claude" bar over the .md corpus
we already build (docs/javascripts/md-actions.js).
- Signature blockquote treatment for the agent transcript; responsive hero
via clamp(); code-fence filename-label styling; richer 404 with a
destinations list + llms.txt link.
- Fix the doubled <title> ("model-ledger — git for models" on home).
- Enable free Material niceties: breadcrumbs, instant prefetch/preview,
code-line selection.
Meta/discoverability
- robots.txt declaring the sitemap; README now links to the docs site.
Deferred (own follow-ups): CHANGELOG reconcile+surface (needs real version
archaeology — won't fabricate versions), vs-MLflow/DataHub comparison page,
build-time per-page OG via the social plugin, print stylesheet.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 064a8704a0
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| |---|---|---| | ||
| | `model-ledger` | SDK, graph, SQL/REST/GitHub connectors | the core library | | ||
| | `model-ledger[mcp]` | MCP server (`model-ledger mcp`) | AI agents — Claude, Goose, Cursor | | ||
| | `model-ledger[rest-api]` | FastAPI app (`model-ledger serve`) | frontends, dashboards | |
There was a problem hiding this comment.
With only model-ledger[rest-api], the console entry point still imports model_ledger.cli.app, which unconditionally imports typer and rich, while the rest-api extra in pyproject.toml only adds FastAPI/uvicorn. Users following this row will hit an import error before model-ledger serve can run unless they also install [cli] or the REST extra includes the CLI dependencies.
Useful? React with 👍 / 👎.
| # Keep internal planning specs and snippet-only includes out of the built site. | ||
| exclude_docs: | | ||
| superpowers/ | ||
| includes/ |
There was a problem hiding this comment.
Adding includes/ here only affects MkDocs' own document collection; the custom docs_hooks/llms_txt.py hook still walks every Markdown file under docs/ except superpowers/ and copies it into the built site. As a result, the new docs/includes/abbreviations.md is still published at /includes/abbreviations.md and indexed in /llms.txt, so the hook needs the same exclusion if this directory is meant to be snippet-only.
Useful? React with 👍 / 👎.
1 participant
A substance + slickness pass on the docs site — everything within the existing "technical-archive" aesthetic (no restyle). Builds on #12.
New pages
Slickness (style-preserving)
.mdcorpus the site already builds — the canonical agent-doc move, fitting for a tool that is an MCP server.clamp()); code-fence filename-label styling; richer 404 (destinations +llms.txtlink); fixed the doubled<title>.Meta
robots.txtdeclaring the sitemap; README now links to the docs site.Deferred (own follow-ups, not fabricated here)
Changelog reconcile + surface (needs real version-history archaeology), a vs-MLflow/DataHub comparison page, build-time per-page OG via Material's social plugin, a print stylesheet.
Verified:
mkdocs build --strictclean; the docs example-doctest passes (the Governance page's snippet runs in CI).🤖 Generated with Claude Code