fix: Update publish.yml

.github/workflows/publish.yml

@@ -1,30 +1,41 @@
 name: Build and Publish
+
 on:
   push:
     branches:
       - main
   workflow_dispatch:
+
 permissions:
   contents: read
   pages: write
   id-token: write
+
 jobs:
   deploy:
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
+
     runs-on: ubuntu-latest
+
     steps:
       - uses: actions/configure-pages@v6
+
       - uses: actions/checkout@v4
+
       - uses: actions/setup-python@v4
         with:
           python-version: 3.x
+
       - run: pip install -r requirements.txt
-      - run: python scripts/prepare_docs.py
+
       - run: zensical build --clean
+
       - uses: actions/upload-pages-artifact@v3
         with:
           path: site
+
       - uses: actions/deploy-pages@v4
         id: deployment
+

DEVELOPING.md

@@ -1,176 +1,72 @@
 # Developing CALYPR Docs
 
-This repo now uses a Zensical-only build pipeline. MkDocs, `.nav.yml`, and the old multirepo plugin are gone.
+Zensical builds the site directly from `docs/`. Upstream tool docs (git-drs, syfon) are fetched from GitHub at build time via `mkdocs-multirepo-plugin`. Navigation is defined in `zensical.toml`.
 
-The main thing to understand is that the published site is built from a generated docs tree, not directly from `docs/`.
-
-## Mental Model
-
-- `docs/` contains repo-authored source content.
-- `.generated/docs/` is the staged build input that Zensical actually reads.
-- `site/` is the rendered output from `zensical build`.
-- `zensical.toml` is the only navigation source of truth.
-
-The build pipeline is:
-
-1. Copy repo-authored docs from `docs/` into `.generated/docs/`
-2. Import selected upstream docs from `git-drs` and `syfon`
-3. Apply a few link rewrites needed for imported pages
-4. Add generated assets like `termynal.css` and `termynal.js`
-5. Run Zensical against `.generated/docs`
-
-## Core Commands
-
-From the repo root:
+## Setup
 
 ```bash
-python3 -m venv venv
-source venv/bin/activate
+python3 -m venv venv && source venv/bin/activate
 pip install -r requirements.txt
 make serve
 ```
 
-Useful commands:
-
-- `make prepare`: rebuild `.generated/docs`
-- `make build`: run a clean Zensical build
-- `make serve`: prepare docs and start the local server
-- `make update-branches`: update GitHub source links in authored docs to the preferred upstream branches
-
-If you want the raw commands:
+## Commands
 
 ```bash
-python scripts/prepare_docs.py
-zensical build --clean
-zensical serve
+make serve  # start local dev server
+make build  # clean build to site/
 ```
 
-## Where Navigation Lives
-
-Navigation is fully defined in [zensical.toml](./zensical.toml).
-
-If you want to:
-
-- rename a sidebar label
-- move a section
-- add a new page to the nav
-- change the Tools grouping
-
-edit the `nav = [...]` structure in `zensical.toml`.
-
-There are no `.nav.yml` files anymore. If you add a page under `docs/` and do not add it to `zensical.toml`, it will not appear in the intended nav structure.
-
-## Source of Truth Rules
-
-### Repo-authored pages
-
-These live in `docs/` and should be edited directly there.
-
-Examples:
-
-- `docs/index.md`
-- `docs/calypr/...`
-- `docs/tools/index.md`
-- `docs/tools/funnel/...`
-- `docs/tools/grip/...`
-
-### Imported tool pages
-
-These are not authored in this repo anymore.
-
-Current imported repos:
-
-- `git-drs`
-- `syfon`
-
-Their imported file mappings live in [scripts/prepare_docs.py](./scripts/prepare_docs.py) under `REPO_IMPORTS`.
-
-If you need to:
+## Navigation
 
-- add a new imported page
-- stop importing a page
-- change where an imported page lands under `tools/...`
+All navigation is defined in `zensical.toml` under `nav = [...]`. A page not listed there will not appear in the sidebar.
 
-update `REPO_IMPORTS` and usually also update `zensical.toml`.
+## Adding pages
 
-Do not hand-edit imported pages under `.generated/docs`. They are build artifacts and will be replaced on the next `make prepare`.
+### Repo-authored page
 
-## How Upstream Imports Work
-
-The importer prefers local sibling repos by default:
-
-- `../git-drs`
-- `../syfon`
-
-So on a typical local machine, the imported content comes from whatever is currently checked out in those repos.
-
-If local sibling repos are unavailable, the importer falls back to GitHub and picks the first available branch from [scripts/branch_config.json](./scripts/branch_config.json).
-
-Current branch preference order:
-
-- `development`
-- `develop`
-- `main`
-- `master`
-
-The last import decision is written to `.generated/imports.json`.
-
-Environment overrides:
-
-- `CALYPR_IMPORT_PREFER_LOCAL=0`: force remote import mode
-- `CALYPR_IMPORT_GIT_DRS_DIR=/path/to/git-drs`: override local `git-drs` source
-- `CALYPR_IMPORT_SYFON_DIR=/path/to/syfon`: override local `syfon` source
-
-## When You Add or Change Pages
-
-### Adding a repo-authored page
-
-1. Create the file under `docs/`
-2. Add it to `zensical.toml`
-3. Run `make serve` or `make build`
-
-### Adding an imported tool page
-
-1. Add the file mapping in `scripts/prepare_docs.py`
-2. Add the page to `zensical.toml`
-3. If the imported markdown links break after relocation, add a targeted rewrite in `MARKDOWN_REWRITES`
-4. Run `make prepare`
-5. Run `make build`
-
-## Styling and Overrides
-
-Site-level assets still come from the repo:
+```bash
+# 1. create the file
+vim docs/calypr/example.md
 
-- custom CSS: `docs/stylesheets/extra.css`
-- custom JS: `docs/javascripts/nav-open-level1.js`
-- theme overrides: `overrides/`
+# 2. add it to nav in zensical.toml, then:
+make serve
+```
 
-Those are copied into `.generated/docs` during preparation and then used by Zensical.
+### Page from an imported repo (git-drs, syfon)
 
-## Deployment Behavior
+```bash
+# 1. add and merge the file in the upstream repo (e.g. calypr/git-drs), then:
 
-Deployment uses the same pipeline as local builds:
+# 2. add the file path to the relevant imports list in zensical.toml:
+#    [[plugins.multirepo.nav_repos]]
+#    name = "git-drs"
+#    imports = ["docs/my-new-page.md", ...]
 
-- GitHub Pages runs `python scripts/prepare_docs.py` and then `zensical build --clean`
-- Netlify does the same
+# 3. add the page to nav in zensical.toml, then:
+make serve  # plugin fetches it automatically
+```
 
-That means deployment now depends on the import step succeeding. In CI, the importer will usually use remote GitHub repos rather than local sibling repos.
+### New imported repo entirely
 
-## Files You Should Usually Ignore
+```bash
+# 1. add a new block to zensical.toml:
+#    [[plugins.multirepo.nav_repos]]
+#    name = "my-tool"
+#    import_url = "https://github.com/calypr/my-tool?branch=development"
+#    imports = ["docs/index.md", ...]
 
-- `.generated/`
-- `site/`
-- `.cache/`
+# 2. add the pages to nav in zensical.toml, then:
+make serve
+```
 
-These are build/runtime artifacts.
+## Styling and overrides
 
-## Known Caveat
+- Custom CSS: `docs/stylesheets/extra.css`
+- Custom JS: `docs/javascripts/nav-open-level1.js`
+- Theme overrides: `overrides/`
 
-Zensical currently reports some warnings from imported and legacy docs content, especially around bracketed literals like:
+## Deployment
 
-- `[SIGNED]`
-- `[0]`
-- `[]string`
-- `map[string]string`
+Netlify runs `zensical build --clean` directly. The multirepo plugin fetches upstream docs from GitHub during the build, so CI always gets the latest from the configured branches.
 
-Those are content/rendering warnings, not a sign that the Zensical migration is broken.

README.md

@@ -15,7 +15,6 @@ make serve
 
 The local build contract is:
 
-- `make prepare` stages repo-authored docs plus imported upstream tool docs into `.generated/docs`
 - `make build` runs a clean Zensical build
 - `make serve` stages the docs and starts the local Zensical server
 
@@ -24,7 +23,6 @@ For repo maintenance details, navigation ownership, and import behavior, see [DE
 If you prefer the raw commands:
 
 ```sh
-python scripts/prepare_docs.py
 zensical serve
 ```
 
@@ -33,3 +31,4 @@ zensical serve
 The site is automatically built and published on every push to `main` using the GitHub Actions workflow in [publish.yml](.github/workflows/publish.yml). Netlify uses the same Zensical build pipeline.
 
 To skip CI for a commit, add `[skip ci]` (or any [equivalent variation](https://docs.github.com/en/actions/managing-workflow-runs/skipping-workflow-runs)) to the commit message.
+