docs: initial site

[jenna-winkler]

Summary

Docs site

Related issue(s)

(Optional) Testing Instructions

Fixes #

[xjacka]

🛡️ Humr — Code Review

PR #321: docs: initial site

Author: jenna-winkler | Branch: docs/site → main | Changes: +562 −0 (16 files)

Summary

This PR sets up a complete MkDocs documentation site for Humr using the Material theme. It covers quickstart, user guides (credentials, scheduling, files, Slack, settings), and self-hosting guides (local dev, Kubernetes deploy, custom agent building), plus mise integration for building/serving the docs.

Findings

• 🟡 Warning: docs/self-hosting/build-a-custom-agent.md:16 — "Humr's controller creates a StatefulSet, a PVC for the workspace, and network policies for isolation" conflicts with PR refactor: replace StatefulSet with single-use Jobs (ADR-012) #140 (currently open), which is replacing StatefulSets with single-use Jobs per ADR-012. This sentence will be immediately stale when refactor: replace StatefulSet with single-use Jobs (ADR-012) #140 merges.
• 🟡 Warning: docs/self-hosting/deploy.md:137 — "Agent pods are managed by StatefulSets — running agents aren't disrupted during a platform upgrade" — same staleness issue. Should be updated to reflect Jobs-based architecture once ADR-012 lands.
• 🟢 Suggestion: mkdocs.yml:12-15 — Link validation is set to info level (not_found: info, unrecognized_links: info). Raising to warn or adding a CI lint step that fails on broken links would catch doc rot early.
• ✅ Looks good: docs/assets/ already contains hero.png and logo.svg — no broken asset references in docs/index.md or mkdocs.yml.
• ✅ Looks good: .gitignore correctly excludes site/ and .venv/.
• ✅ Looks good: mise.toml integration is minimal — just adds uv and includes docs/tasks.toml. No unnecessary changes.
• ✅ Looks good: Documentation content is accurate, clearly written, and covers all major user journeys in a logical structure.

Verdict

COMMENT — Well-written docs with good coverage, but the two StatefulSet references conflict with the open ADR-012 refactor in PR #140; coordinate the wording update before or alongside that merge.

---

Review by Humr · automated code guardian

[xjacka]

🛡️ Humr — Code Review

PR #321: docs: initial site

Author: jenna-winkler | Branch: docs/site → main | Changes: +589 −0 (16 files)

Summary

Adds a complete MkDocs-based documentation site covering user quickstart, user guide (chatting, credentials, files, Slack, scheduling, management), and self-hosting guides (local dev, Kubernetes deployment, custom agent). Also adds packages/agents/claude-code/workspace/.claude/settings.json with Claude Code model configuration.

Changes since last review

Previous HEAD: e923be6 (2026-04-27T00:00:00Z) — verdict APPROVE

• 🔁 Still present: get-started.md — http://humr.localhost:4444 link without an explicit dev-only callout (docs/self-hosting/get-started.md) — carried over from previous review
• 🔁 Still present: deploy.md — nfsProvisioner section without a "not production-grade" warning (docs/self-hosting/deploy.md) — carried over from previous review
• 🆕 New: packages/agents/claude-code/workspace/.claude/settings.json — new file adding Claude Code workspace model settings with potentially outdated model IDs

Findings

• 🟡 Warning: packages/agents/claude-code/workspace/.claude/settings.json — availableModels lists older Claude model IDs (claude-sonnet-4-5-20250929, claude-opus-4-5-20251101) and the default model is claude-opus-4-6 (older Opus); newer recommended models (claude-opus-4-7, claude-sonnet-4-6) are absent. Users selecting listed models may hit deprecated-model errors. (packages/agents/claude-code/workspace/.claude/settings.json)
• 🟢 Suggestion: mkdocs.yml sets validation.links.not_found: info — silently allows broken links; consider raising to warn so CI catches dead links during docs:build. (mkdocs.yml)
• 🟢 Suggestion: docs/self-hosting/get-started.md — the ## Log in section links to http://humr.localhost:4444 without an explicit note that this URL only works locally; a note callout would prevent confusion. (docs/self-hosting/get-started.md)
• 🟢 Suggestion: docs/self-hosting/deploy.md — the nfsProvisioner block doesn't warn that in-cluster NFS is development-only and not suitable for production. (docs/self-hosting/deploy.md)
• ✅ Looks good: mkdocs.yml exclude_docs prevents internal plans, ADRs, strategy, and architecture docs from leaking to the public site.
• ✅ Looks good: credentials.md honestly discloses the credential proxy's trust limitation (content not inspected; prompt-injection-style exfiltration remains possible through granted hosts).
• ✅ Looks good: scheduling.md documents quiet-hours drops (not queued) explicitly — prevents future user confusion.

Verdict

APPROVE — High-quality documentation site; the stale model IDs in settings.json are worth fixing before heavy user adoption but don't block the docs content.

---

Review by Humr · automated code guardian

[xjacka]

🛡️ Humr — Code Review

PR #321: docs: initial site

Author: jenna-winkler | Branch: docs/site → main | Changes: +578 −0 (15 files)

Summary

Restructures and expands the MkDocs documentation site: replaces docs/self-hosting/ hierarchy with a cleaner flat layout (docs/quickstart.md, docs/deploy.md), adds a full user guide (docs/user-guide/* — chatting, credentials, files, Slack, scheduling, sharing, templates), a welcome page (docs/index.md), and mkdocs.yml site config. Also adds a Claude Code workspace settings file with model IDs. (No PR-local overrides suppressed.)

Changes since last review

Previous HEAD: 45bc290 (2026-04-28T00:00:00Z) — verdict APPROVE

• ✅ Fixed: docs/quickstart.md now contains a !!! note "Local cluster limitations" admonition before the log-in URL, clearly marking the local setup as dev/evaluation-only — previous localhost-link ambiguity concern is resolved.
• 🔁 Still present: settings.json — outdated default model: claude-opus-4-6 and stale availableModels list. (packages/agents/claude-code/workspace/.claude/settings.json)
• 🔁 Still present: mkdocs.yml — validation.links.not_found: info not raised to warn. (mkdocs.yml)
• 🔁 Still present: docs/deploy.md — nfsProvisioner block says "dev clusters" but lacks explicit "not production-grade" warning. (docs/deploy.md)
• 🆕 New: docs/user-guide/templates.md — describes controller creating a StatefulSet, which conflicts with ADR-012 (PR refactor: replace StatefulSet with single-use Jobs (ADR-012) #140) replacing StatefulSets with Jobs. (docs/user-guide/templates.md)
• 🆕 New: docs/user-guide/templates.md — example Dockerfile uses FROM humr-base:latest, a non-pinned tag. (docs/user-guide/templates.md)

Findings

• 🟡 Warning: packages/agents/claude-code/workspace/.claude/settings.json — model: claude-opus-4-6 is not a recognized model ID (current Opus is claude-opus-4-7); availableModels lists deprecated IDs (claude-sonnet-4-5-20250929, claude-opus-4-5-20251101) while omitting current ones (claude-opus-4-7, claude-sonnet-4-6). Users will hit model-not-found errors. (packages/agents/claude-code/workspace/.claude/settings.json)
• 🟡 Warning: docs/user-guide/templates.md — "Humr's controller creates a StatefulSet" conflicts with ADR-012 (PR refactor: replace StatefulSet with single-use Jobs (ADR-012) #140 refactors to single-use Jobs); if that PR merges, this doc ships incorrect behavior. (docs/user-guide/templates.md)
• 🟢 Suggestion: docs/user-guide/templates.md — example Dockerfile uses FROM humr-base:latest; pin to a specific tag for reproducible builds. (docs/user-guide/templates.md)
• 🟢 Suggestion: mkdocs.yml — raise validation.links.not_found from info to warn so broken links are caught during docs:build. (mkdocs.yml)
• 🟢 Suggestion: docs/deploy.md — add an explicit "not production-grade" warning to the nfsProvisioner section. (docs/deploy.md)
• ✅ Looks good: docs/quickstart.md admonition clearly marks local cluster limitations, directing production users to the Kubernetes deployment guide.
• ✅ Looks good: credentials.md transparently discloses the proxy's trust model limitation (content not inspected; exfiltration through granted hosts remains possible).
• ✅ Looks good: scheduling.md explicitly states quiet-hours fires are dropped, not queued.
• ✅ Looks good: mkdocs.yml exclude_docs prevents internal ADRs, plans, and architecture docs from leaking to the public site.

Verdict

APPROVE — Comprehensive, well-structured documentation; the stale StatefulSet reference in templates.md and outdated model IDs in settings.json are worth fixing before wider adoption but don't block merging the docs.

---

Review by Humr · automated code guardian