Rebuild the Documentation Around the User Journey - #67
Merged
Conversation
|
Warning Review limit reached
Next review available in: 43 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: ⛔ Files ignored due to path filters (3)
📒 Files selected for processing (43)
📝 WalkthroughWalkthroughThis PR restructures Heartwood’s public documentation around a new landing page, navigation hierarchy, operational guides, and condensed design contracts. It adds CLI, installation, platform, model, troubleshooting, and deployment guidance while clarifying security, audit, testing, and authorization boundaries. Documentation staging now uses explicit file lists and hashed v2 markers, with updated release checks and tests. Local-model fixtures and browser smoke tests are also aligned with the revised runtime and screenshot workflows. Possibly related issues
Possibly related PRs
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
PSchmiedmayer
force-pushed
the
feature/documentation
branch
from
July 18, 2026 03:02
57857bb to
e90472f
Compare
There was a problem hiding this comment.
Pull request overview
Rebuilds Heartwood’s documentation to follow a progressive user journey (environment → install → project/state → interfaces → models → operators/architecture), adds a dedicated documentation home, and updates staging/publication machinery to publish only an explicit documentation allowlist.
Changes:
- Reorganizes MkDocs/Zensical navigation and rewrites most user/operator docs to align with current implementation boundaries and workflows (container, Terra, Carina, native).
- Introduces a new public documentation home (
documentation/index.md) and new reference pages (e.g., native installation + CLI command reference), while removing the olddocs/README.mdindex. - Tightens documentation staging to an explicit allowlist and updates smoke/system-test scripts that generate and validate documentation screenshots.
Reviewed changes
Copilot reviewed 42 out of 46 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| zensical.toml | Reworks site navigation to match the new user-journey structure. |
| README.md | Simplifies repo landing page, updates quick start and responsibility framing, tweaks release badge target. |
| packages/webui/scripts/smoke-reference-analysis.cjs | Adjusts env for smoke run, captures new action-review screenshot, updates expected tool/audit counts. |
| packages/compliance/tests/test_release_governance.py | Updates release-governance doc version assertions for platform support page. |
| packages/compliance/tests/test_container_assets.py | Removes assertions tied to old offline-guide wording/commands. |
| images/generic/scripts/local_model_stub.py | Refactors terminal tool-call construction; adds extra cat tool-call; uses runtime-root indirection. |
| documentation/index.md | Adds new public documentation home page (user journey entrypoint). |
| docs/web-interface.md | Renames/reframes interface doc; updates responsibilities and shared-state explanation. |
| docs/using-heartwood.md | Renames/reframes daily workflow guidance; expands Skills and audit sections; updates screenshots. |
| docs/troubleshooting.md | Condenses troubleshooting into a shorter readiness-first guide with concrete commands. |
| docs/terra-jupyter-demo.md | Major restructure into a shorter numbered workflow; updates credential handling guidance for notebook. |
| docs/terra-jupyter-demo.ipynb | Adds credential prompt cell and updates narrative for token handling and setup flow. |
| docs/releases.md | Condenses maintainer release instructions and documentation recovery guidance. |
| docs/README.md | Removes legacy documentation index page. |
| docs/project-state.md | Renames/reframes project boundary and .heartwood/ description to match current docs. |
| docs/platforms.md | Renames/reframes environment selection guidance; updates guide links and boundaries. |
| docs/platform-support.md | Replaces detailed evidence matrix with an “available artifacts/interfaces” summary and boundary notes. |
| docs/platform-images.md | Condenses maintainer platform-image contract and verification guidance. |
| docs/model-connections.md | Renames/reframes model connection guide; updates provider options and credential boundary statements. |
| docs/installation.md | Adds native installation instructions and clarifies native-vs-container capability differences. |
| docs/getting-started.md | Rewrites first-use flow to align with new journey and interface/model responsibilities. |
| docs/getting-started-offline.md | Rewrites local-model lifecycle, offline workflow, and command examples. |
| docs/deployment.md | Reframes operator responsibilities and validation checklist for deployments. |
| docs/container-images.md | Rewrites container usage guide; clarifies CPU vs NVIDIA image usage and project persistence. |
| docs/cli-reference.md | Adds a CLI command reference page for common commands and categories. |
| docs/carina-cli.md | Restructures Carina workflow; clarifies gateway vs local-model path and adds external references. |
| docs/assets/web-action-review.png.license | Adds license metadata for the new documentation screenshot asset. |
| design/08-development.md | Renames/restructures development doc; clarifies documentation ownership and release practices. |
| design/07-testing-eval.md | Renames to “Testing and Evidence” and reframes test layers/evidence boundaries. |
| design/06-observability-audit.md | Reframes audit/session distinction and what is recorded vs exported. |
| design/05-security-compliance.md | Renames to “Security and Data Boundaries” and clarifies trust boundaries and credential handling. |
| design/04-skills.md | Reframes Skills vs extensions, metadata intent, and install/validation boundary. |
| design/02-platforms.md | Renames to “Deployment Architecture” and updates the platform/deployment narrative. |
| design/01-overview.md | Renames to “Product and Scope” and updates capability/limits framing. |
| deploy/verify_release_candidate.py | Updates version-string assertions for platform support doc. |
| deploy/tests/versioned_documentation_smoke.sh | Updates smoke test to point at staged index.md instead of removed docs index. |
| deploy/stage_documentation.py | Switches to explicit docs allowlist staging; adds v2 staging marker based on staged tree digest. |
| CONTRIBUTING.md | Updates link target from removed docs index to new documentation home. |
| AGENTS.md | Updates canonical-doc table to reference new documentation structure and additions. |
| ACRONYMS.md | Refactors glossary organization/content to align with updated documentation set. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@ACRONYMS.md`:
- Line 52: Update the llama.cpp row in the “Models and Compute” table to provide
all three columns: Term, Expansion, and Meaning. Preserve the existing
description as the Meaning value and add the appropriate Expansion entry so the
row renders with the same structure as the surrounding rows.
In `@design/05-security-compliance.md`:
- Line 69: Update the attribution sentence in the deployment and use-case
discussion to replace “The Stanford Schmiedmayer Lab” with the canonical “The
Schmiedmayer Lab at Stanford University,” leaving the rest of the sentence
unchanged.
In `@images/generic/scripts/local_model_stub.py`:
- Around line 33-49: Update _terminal_call to accept a security-risk parameter
and use it when constructing the terminal payload instead of hardcoding "LOW";
pass "MEDIUM" from the curl branch and preserve LOW for other callers. Add or
update tests to assert the curl path emits a medium-risk payload.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 90f7fbea-037d-4bd0-915d-d2ae8b541bb7
⛔ Files ignored due to path filters (3)
docs/assets/web-action-review.pngis excluded by!**/*.pngdocs/assets/web-notebook-viewport.pngis excluded by!**/*.pngdocs/assets/web-reference-analysis.pngis excluded by!**/*.png
📒 Files selected for processing (42)
ACRONYMS.mdAGENTS.mdCONTRIBUTING.mdREADME.mddeploy/stage_documentation.pydeploy/tests/versioned_documentation_smoke.shdeploy/verify_release_candidate.pydesign/01-overview.mddesign/02-platforms.mddesign/03-architecture.mddesign/04-skills.mddesign/05-security-compliance.mddesign/06-observability-audit.mddesign/07-testing-eval.mddesign/08-development.mddocs/README.mddocs/assets/web-action-review.png.licensedocs/carina-cli.mddocs/cli-reference.mddocs/container-images.mddocs/deployment.mddocs/getting-started-offline.mddocs/getting-started.mddocs/installation.mddocs/model-connections.mddocs/platform-images.mddocs/platform-support.mddocs/platforms.mddocs/project-state.mddocs/releases.mddocs/terra-jupyter-demo.ipynbdocs/terra-jupyter-demo.mddocs/troubleshooting.mddocs/using-heartwood.mddocs/web-interface.mddocumentation/index.mdimages/generic/scripts/local_model_stub.pypackages/compliance/tests/test_container_assets.pypackages/compliance/tests/test_documentation_assets.pypackages/compliance/tests/test_release_governance.pypackages/webui/scripts/smoke-reference-analysis.cjszensical.toml
💤 Files with no reviewable changes (2)
- docs/README.md
- packages/compliance/tests/test_container_assets.py
PSchmiedmayer
force-pushed
the
feature/documentation
branch
from
July 18, 2026 03:16
e90472f to
8311a25
Compare
PSchmiedmayer
added a commit
that referenced
this pull request
Jul 18, 2026
### ♻️ Current Situation & Problem Heartwood documentation had grown around implementation phases and platform validation sessions. It mixed user guidance with run-specific evidence and planned work, repeated setup paths, and used outdated narrow screenshots. This rebuild establishes a professional release-facing documentation set and builds on the versioned publication work tracked in #36. Deferred product gaps are tracked separately in #64, #65, and #66. ### ⚙️ Release Notes - Reorganize the documentation around a progressive journey from environment selection and first use through models, interfaces, managed platforms, operations, and architecture. - Clarify the shared current-directory project contract, private `.heartwood/` state, model connection paths, grouped action review, and the supported Terra and Carina workflows. - Replace outdated screenshots with current desktop captures generated by the browser and CLI system test. - Separate current user guidance and durable technical rationale from planned work, implementation discussion, and run-specific evidence. ### 📚 Documentation - Add a dedicated public documentation home, installation guide, and command reference, and simplify the repository README. - Rewrite the user, operator, architecture, security, testing, platform, model, and troubleshooting pages against the current implementation. - Publish only an explicit documentation allowlist and bind staging ownership to the complete staged content tree. - Preserve planned implementation and acceptance criteria in GitHub Issues and the Heartwood Project. ### ✅ Testing - Passed all 615 Python tests with 90.31% coverage, Ruff, mypy, fixture validation, REUSE, yamllint, and actionlint. - Passed all 63 web unit tests, two Playwright workflows, and the gateway, Jupyter proxy, grouped action, CLI replay, audit, and reference-analysis system tests. - Passed the strict Zensical build, versioned stable/preview publication smoke test, immutable model-source verification, npm license audit, and npm vulnerability audit. - Reviewed the rendered documentation at desktop and mobile viewports. ### Code of Conduct & Contributing Guidelines By creating and submitting this pull request, you agree to follow our [Code of Conduct](https://github.com/SchmiedmayerLab/.github/blob/main/CODE_OF_CONDUCT.md) and [Contributing Guidelines](https://github.com/SchmiedmayerLab/.github/blob/main/CONTRIBUTING.md): - [x] I agree to follow the [Code of Conduct](https://github.com/SchmiedmayerLab/.github/blob/main/CODE_OF_CONDUCT.md) and [Contributing Guidelines](https://github.com/SchmiedmayerLab/.github/blob/main/CONTRIBUTING.md).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
♻️ Current Situation & Problem
Heartwood documentation had grown around implementation phases and platform validation sessions. It mixed user guidance with run-specific evidence and planned work, repeated setup paths, and used outdated narrow screenshots. This rebuild establishes a professional release-facing documentation set and builds on the versioned publication work tracked in #36. Deferred product gaps are tracked separately in #64, #65, and #66.
⚙️ Release Notes
.heartwood/state, model connection paths, grouped action review, and the supported Terra and Carina workflows.📚 Documentation
✅ Testing
Code of Conduct & Contributing Guidelines
By creating and submitting this pull request, you agree to follow our Code of Conduct and Contributing Guidelines: