Reframe Privacy Guard documentation

.github/workflows/docs-preview-deploy.yml

@@ -99,14 +99,18 @@ jobs:
                 'scripts/build-docs.sh',
                 'scripts/publish-agent-markdown.py',
                 'scripts/render-dev-notes.py',
+                'scripts/stage-privacy-guard-docs.py',
                 'tests/test_agent_markdown.py',
                 'tests/test_docs_404.py',
                 'tests/test_render_dev_notes.py',
+                'tests/test_stage_privacy_guard_docs.py',
                 'zensical.toml',
               ]);
               const docsChanged = files.some(
                 ({ filename }) => filename.startsWith('docs/') ||
-                  filename.startsWith('overrides/') || exactInputs.has(filename),
+                  filename.startsWith('overrides/') ||
+                  filename.startsWith('projects/privacy-guard/docs/') ||
+                  exactInputs.has(filename),
               );
               operation = docsChanged ? 'deploy' : 'remove';
             }

.github/workflows/docs-preview.yml

@@ -47,14 +47,18 @@ jobs:
               'scripts/build-docs.sh',
               'scripts/publish-agent-markdown.py',
               'scripts/render-dev-notes.py',
+              'scripts/stage-privacy-guard-docs.py',
               'tests/test_agent_markdown.py',
               'tests/test_docs_404.py',
               'tests/test_render_dev_notes.py',
+              'tests/test_stage_privacy_guard_docs.py',
               'zensical.toml',
             ]);
             const docsChanged = files.some(
               ({ filename }) => filename.startsWith('docs/') ||
-                filename.startsWith('overrides/') || exactInputs.has(filename),
+                filename.startsWith('overrides/') ||
+                filename.startsWith('projects/privacy-guard/docs/') ||
+                exactInputs.has(filename),
             );
             core.setOutput('operation', docsChanged ? 'deploy' : 'remove');
 

.github/workflows/docs.yml

@@ -59,7 +59,8 @@ jobs:
       - name: Upload production documentation
         if: >-
           github.ref == 'refs/heads/main' &&
-          github.event_name == 'workflow_dispatch'
+          (github.event_name == 'push' ||
+          github.event_name == 'workflow_dispatch')
         uses: actions/upload-artifact@v7
         with:
           name: production-docs-${{ github.run_id }}
@@ -71,7 +72,8 @@ jobs:
     name: Deploy documentation
     if: >-
       github.ref == 'refs/heads/main' &&
-      github.event_name == 'workflow_dispatch'
+      (github.event_name == 'push' ||
+      github.event_name == 'workflow_dispatch')
     needs: validate
     runs-on: ubuntu-latest
     permissions:

.gitignore

@@ -121,6 +121,7 @@ lib/
 # Static site and docs output
 public/
 site/
+docs/documentation/privacy-guard/
 .docusaurus/
 .vitepress/cache/
 .vitepress/dist/

AGENTS.md

@@ -8,7 +8,8 @@ documentation for work that uses OpenShell as its runtime.
 ## Work routing
 
 - Put self-contained implementations and experiments in `projects/<name>/`.
-- Put durable user-facing guides and references in `docs/documentation/`.
+- Put project-specific user guides and references in `projects/<name>/docs/`.
+- Put cross-project user-facing documentation in `docs/documentation/`.
 - Put Dev Notes (human-written technical notes) `docs/dev-notes/`.
 - Put agent-facing repository maintenance workflows in `docs/development/`.
 
@@ -32,6 +33,9 @@ read `docs/development/index.md`.
   `.env.example`.
 - Do not hand-edit generated Dev Notes cards, bylines, or navigation; use
   `python3 scripts/render-dev-notes.py`.
+- Do not hand-edit generated project-documentation mirrors under
+  `docs/documentation/`; use the project's canonical `docs/` tree and its
+  documented staging script.
 - When adding a project or workflow with distinct conventions, add a nested
   `AGENTS.md` in that directory instead of expanding this root file.
 

docs/development/index.md

@@ -5,35 +5,39 @@ description: Agent instructions for maintaining the OpenShell Research documenta
 
 # Documentation site development
 
-Follow these instructions for changes under `docs/`, `zensical.toml`, the Dev
-Notes renderer, or the documentation workflow. Run commands from the repository
-root. Use Python 3.10 or newer.
+Follow these instructions for changes under `docs/`, a project's `docs/` tree,
+`zensical.toml`, the Dev Notes renderer, or the documentation workflow. Run
+commands from the repository root. Use Python 3.10 or newer.
 
 ## Content routing
 
-- Put durable software knowledge—installation, usage, reproducibility, and known
-  limitations—under `docs/documentation/`.
+- Put project-specific software knowledge—installation, usage, reproducibility,
+  and known limitations—under `projects/<name>/docs/`. The clean build stages
+  configured project documentation under `docs/documentation/` for publishing.
+- Put cross-project software documentation directly under
+  `docs/documentation/`.
 - Put dated experiments, benchmarks, releases, use cases, and engineering updates
   under `docs/dev-notes/`.
-- When a Dev Note introduces reusable software, add its durable guide under
-  `docs/documentation/`, link it to the originating Dev Note, and add it to
-  `zensical.toml`.
+- When a Dev Note introduces reusable software, add its durable guide to the
+  owning project, link it to the originating Dev Note, and add its staged site
+  path to `zensical.toml`.
 
 ## Agent-readable Markdown
 
-Every canonical content page under `docs/dev-notes/posts/` and
-`docs/documentation/` must declare `agent_markdown: true` in its front matter.
-The clean site build copies those sources byte-for-byte into `site/` at the same
-path relative to `docs/`, and each rendered page links to its same-origin
-Markdown source for people and agents. The generated copies under `site/` must
-not be edited.
-
-Every page in the two canonical content directories is published, including
-the Documentation index. Keep presentation-only landing pages such as the
-homepage and Dev Notes card index, redirect-only pages, obsolete or orphan
-project pages, internal development documentation, and the 404 page outside
-those directories and do not add the marker to them. Those pages are not
-canonical content for agent consumption.
+Every canonical content page under `docs/dev-notes/posts/`,
+`docs/documentation/`, and a staged project documentation tree must declare
+`agent_markdown: true` in its front matter. The clean site build first stages
+project documentation, then copies all published Markdown sources byte-for-byte
+into `site/` at their site paths. Each rendered page links to its same-origin
+Markdown source for people and agents. Generated copies under
+`docs/documentation/` and `site/` must not be edited.
+
+Every page in a published content tree is included, including the Documentation
+index. Keep presentation-only landing pages such as the homepage and Dev Notes
+card index, redirect-only pages, obsolete or orphan project pages, internal
+development documentation, and the 404 page outside those trees and do not add
+the marker to them. Those pages are not canonical content for agent
+consumption.
 
 ## Dev Notes
 
@@ -88,8 +92,10 @@ scripts/build-docs.sh
 ```
 
 `scripts/build-docs.sh` recreates `.venv-docs`, installs the pinned toolchain,
-renders Dev Notes metadata, and runs `zensical build --clean --strict`. Do not
-report success unless it completes without issues.
+stages canonical Privacy Guard documentation from
+`projects/privacy-guard/docs/`, renders Dev Notes metadata, and runs
+`zensical build --clean --strict`. Do not report success unless it completes
+without issues.
 
 For documentation-site changes, serve the complete built artifact before
 handing the task back:
@@ -110,11 +116,11 @@ previews on the production documentation origin.
 
 The `gh-pages` branch stores the composite production site and active previews;
 GitHub Pages remains configured with **GitHub Actions** as its publishing
-source. Pushes to `main` validate documentation without publishing it. When the
-current documentation is ready for production, manually run the **Docs**
-workflow from `main`; that run updates the production site while preserving
-active previews, then deploys the complete branch through the official Pages
-artifact workflow. The first production deployment creates `gh-pages`
-automatically. To roll back to a revision before preview support, leave the
-Pages source set to **GitHub Actions** and rerun the restored documentation
-workflow.
+source. Every successful push to `main` updates the production site while
+preserving active previews, then deploys the complete branch through the
+official Pages artifact workflow. Merging a pull request therefore publishes
+its documentation after the **Docs** workflow passes. A manual **Docs**
+workflow dispatch from `main` can republish the current revision without a new
+commit. The first production deployment creates `gh-pages` automatically. To
+roll back to a revision before preview support, leave the Pages source set to
+**GitHub Actions** and rerun the restored documentation workflow.

docs/documentation/index.md

@@ -9,6 +9,4 @@ agent_markdown: true
 Technical documentation and references for installing, using, and extending
 OpenShell Research projects.
 
-- [Privacy Guard architecture](privacy-guard/architecture/index.md): component
-  boundaries, request flow, extension interfaces, concurrency, failures, and
-  limits
+- [Privacy Guard](privacy-guard/index.md): middleware for protecting sensitive data in OpenShell.