⚙️ [Maintenance]: Documentation site migrated to Zensical (#31)

The documentation site is now built with
[Zensical](https://zensical.org/) instead of Material for MkDocs. The
Blog section has been removed from the site and navigation. All other
documentation pages remain accessible at their current URLs, now served
by Zensical's `modern` theme.

- Fixes #30

## Removed: Blog section

The Blog section and all its content have been removed from the site and
navigation. The RSS feed and social preview cards, which depended on
third-party plugins not yet available in Zensical, have also been
removed. These features are tracked on Zensical's roadmap and can be
re-enabled once the corresponding native modules ship.

## Changed: Documentation site built with Zensical

The site is now generated by [Zensical](https://zensical.org/), the
next-generation platform built by the creators of Material for MkDocs.
The `modern` theme variant (Zensical's default) is active. The
`overrides/` customizations and `includes/` snippets carry over
unchanged, as Zensical's HTML structure is compatible with both theme
variants.

## Technical Details

**`mkdocs.yml` → `zensical.toml`**
All settings translated to native TOML under the `[project]` scope. The
`mkdocs.yml` compatibility shim was not used. `modern` is the Zensical
default, so no `variant` key is set.

**Plugins**
Five Tier 2 plugins dropped entirely: `git-committers`,
`git-revision-date-localized`, `rss`, `social` (via
`mkdocs-material[imaging]`), and `table-reader` — all on Zensical's Tier
2 backlog and not yet available as native modules. Dependent site
features (contributor avatars, last-modified dates, RSS feed, social
preview cards) are removed with them. `meta` (Tier 1) and `search`
(built-in default) are retained.

**Blog content deleted**
`docs/Blog/index.md`, `docs/Blog/.authors.yml`,
`docs/Blog/Posts/test.md`, `docs/Blog/Posts/.meta.yml` — all existed
solely as blog plugin inputs.

**`Docs.yml` CI workflow rewritten**
Full replacement with Zensical's recommended GitHub Pages pattern:
`configure-pages` → `checkout` → `setup-python` → `pip install zensical`
→ `zensical build --clean` → `upload-pages-artifact` → `deploy-pages`.
`MATERIAL_FOR_MKDOCS_INSIDER_PAT`, `MKDOCS_GIT_COMMITTERS_APIKEY`, the
`PSModule/GitHub-Script` connect step, and all plugin install steps
removed. `contents: write` downgraded to `contents: read`. `uv` adoption
deferred per planning decision.

**Implementation plan progress:** All four groups from issue #30 Section
3 complete in this PR — prep (create `zensical.toml`), prep (remove Blog
content), migrate (update `Docs.yml`), cleanup (delete `mkdocs.yml`).
The four groups ship atomically because each intermediate state would
leave the repo in a broken build.

---------

Co-authored-by: psmodule-s-scribbler <199736790+psmodule-s-scribbler@users.noreply.github.com>

Author: MariusStorhaug

.github/dependabot.yml

@@ -12,3 +12,5 @@ updates:
       - github-actions
     schedule:
       interval: weekly
+    cooldown:
+      default-days: 7

.github/linters/.codespellrc

@@ -0,0 +1,3 @@
+[codespell]
+skip = ./.github/linters
+ignore-words-list = afterall

.github/linters/.powershell-psscriptanalyzer.psd1

@@ -50,6 +50,7 @@
         }
     }
     ExcludeRules = @(
+        'PSAvoidUsingWriteHost',        # Write-Host is acceptable in guidance scripts.
         'PSMissingModuleManifestField', # This rule is not applicable until the module is built.
         'PSUseToExportFieldsInManifest'
     )

.github/workflows/Docs.yml

@@ -7,52 +7,47 @@ on:
       - main
     paths:
       - docs/**
-      - mkdocs.yml
+      - zensical.toml
       - .github/workflows/Docs.yml
 
-env:
-  GH_TOKEN: ${{ github.token }}
-  MKDOCS_GIT_COMMITTERS_APIKEY: ${{ github.token }}
-
-defaults:
-  run:
-    shell: pwsh
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
 
 permissions:
-  contents: write  # to push GitHub Pages to the gh-pages branch
-  pages: write    # to deploy to Pages
-  id-token: write # to verify the deployment originates from an appropriate source
+  contents: read
 
 jobs:
   build:
-    runs-on: ubuntu-latest
+    name: Build and deploy docs
+    runs-on: ubuntu-24.04
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    permissions:
+      contents: read
+      pages: write # deploy to GitHub Pages
+      id-token: write # OIDC token for actions/deploy-pages
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5.0.0
+
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
         with:
-          fetch-depth: 0
           persist-credentials: false
 
-      - name: Connect to GitHub
-        uses: PSModule/GitHub-Script@0097f3bbe3f413f3b577b9bcc600727b0ca3201a # v1.7.10
-
-      - name: Install mkdocs-material
-        env:
-          GH_TOKEN: ${{ secrets.MATERIAL_FOR_MKDOCS_INSIDER_PAT }}
-        run: |
-          pip install git+https://$env:GH_TOKEN@github.com/squidfunk/mkdocs-material-insiders.git
-
-      - name: Install plugins
-        run: |
-          pip install mkdocs-git-authors-plugin
-          pip install mkdocs-git-revision-date-localized-plugin
-          pip install mkdocs-git-committers-plugin-2
-          pip install mkdocs-rss-plugin
-          pip install "mkdocs-material[imaging]"
-          pip install mkdocs-table-reader-plugin
-
-      - name: Build mkdocs-material project
-        run: |
-          mkdocs build --config-file ./mkdocs.yml --strict --site-dir _site/
-
-      - name: Deploy to GitHub Pages
-        run: mkdocs gh-deploy --force
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: 3.x
+
+      - name: Install Zensical
+        run: pip install zensical
+
+      - name: Build Zensical project
+        run: zensical build --clean
+
+      - uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4.0.0
+        with:
+          path: site
+
+      - uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5
+        id: deployment

.github/workflows/Linter.yml

@@ -1,6 +1,6 @@
 name: Linter
 
-run-name: "Linter - [${{ github.event.pull_request.title }} #${{ github.event.pull_request.number }}] by @${{ github.actor }}"
+run-name: 'Linter - [${{ github.event.pull_request.title }} #${{ github.event.pull_request.number }}] by @${{ github.actor }}'
 
 on: [pull_request]
 
@@ -9,27 +9,29 @@ concurrency:
   cancel-in-progress: true
 
 permissions:
-  contents: read
-  packages: read
-  statuses: write
+  contents: read # checkout the repository
+  packages: read # read packages for dependency review
+  statuses: write # report linter status checks
 
 jobs:
   Lint:
     name: Lint code base
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repo
-        uses: actions/checkout@v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           fetch-depth: 0
           persist-credentials: false
 
       - name: Lint code base
-        uses: super-linter/super-linter@latest
+        uses: super-linter/super-linter@9e863354e3ff62e0727d37183162c4a88873df41 # v8.6.0
         env:
           GITHUB_TOKEN: ${{ github.token }}
+          VALIDATE_BIOME_LINT: false
           VALIDATE_BIOME_FORMAT: false
           VALIDATE_JSCPD: false
           VALIDATE_JSON_PRETTIER: false
           VALIDATE_MARKDOWN_PRETTIER: false
           VALIDATE_YAML_PRETTIER: false
+          VALIDATE_HTML_PRETTIER: false

.github/workflows/Update-Index.yml

@@ -14,13 +14,14 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           persist-credentials: false
 
       - name: Update index
         uses: PSModule/GitHub-Script@0097f3bbe3f413f3b577b9bcc600727b0ca3201a # v1.7.10
         with:
-          ClientID: ${{ secrets.SCRIBBLER_BOT_CLIENT_ID }}
-          PrivateKey: ${{ secrets.SCRIBBLER_BOT_PRIVATE_KEY }}
+          # Org-level shared secrets used across multiple repositories — no dedicated GitHub Environment needed.
+          ClientID: ${{ secrets.SCRIBBLER_BOT_CLIENT_ID }} # zizmor: ignore[secrets-outside-env]
+          PrivateKey: ${{ secrets.SCRIBBLER_BOT_PRIVATE_KEY }} # zizmor: ignore[secrets-outside-env]
           Script: .github/scripts/Update-Index.ps1

docs/Agents/Git-Worktrees.md

@@ -0,0 +1,130 @@
+# Git Worktrees
+
+All repositories are set up as **bare clones with worktrees**. This enables parallel work — multiple agents (or a human and an agent) can work on different issues in the same repository simultaneously without conflicts, stashing, or context-switching.
+
+## Why worktrees
+
+| Problem with traditional clones              | How worktrees solve it                                    |
+| -------------------------------------------- | --------------------------------------------------------- |
+| Only one branch checked out at a time        | Each issue gets its own worktree — parallel by default    |
+| Switching branches requires clean state      | Worktrees are independent — no stashing or committing WIP |
+| Agent work blocks human work on same repo    | Different worktrees, no interference                      |
+| Default branch gets dirty during development | `main/` worktree is always a clean reference              |
+
+## Repository layout
+
+```text
+<repo-root>/
+├── .bare/              # bare git data (the actual repository)
+├── .git                # file containing: gitdir: ./.bare
+├── main/               # worktree: default branch (always clean, never worked in directly)
+├── 42-add-pagination/  # worktree: issue #42 in progress
+└── 99-fix-null-ref/    # worktree: issue #99 in progress
+```
+
+- **`.bare/`** — the shared git object store. All worktrees share this.
+- **`.git`** — a file (not a directory) that points git tooling to `.bare/`.
+- **`main/`** — the default branch worktree. Kept as a clean reference. Used for diffing, reading docs, running comparisons. Never directly committed to.
+- **`<N>-<slug>/`** — one worktree per issue in flight. Named by issue number and a short slug. Branch name matches the folder name.
+
+## Remotes
+
+Every repository has exactly two remotes (or one, if it is not a fork):
+
+| Remote         | Points to                    | Required | Purpose                                          |
+| -------------- | ---------------------------- | -------- | ------------------------------------------------ |
+| **`origin`**   | Our copy on the server       | Always   | Push branches, open PRs, CI runs against this.   |
+| **`upstream`** | The parent repo (forks only) | Forks    | Track upstream changes, sync the default branch. |
+
+No other remotes are added. This keeps the model simple and predictable for both humans and agents.
+
+### How it works in practice
+
+- **Non-fork repos** — only `origin` exists. Branches are pushed to `origin`, PRs are opened against `origin`.
+- **Forked repos** — `origin` is our fork, `upstream` is the original repository. The default branch tracks `upstream` for syncing; feature branches are pushed to `origin` and PRs are opened from `origin` into `upstream`.
+
+### Fetch configuration
+
+Both remotes are configured with full refspecs so `git fetch --all --prune` keeps everything current:
+
+```text
+[remote "origin"]
+    fetch = +refs/heads/*:refs/remotes/origin/*
+
+[remote "upstream"]   # forks only
+    fetch = +refs/heads/*:refs/remotes/upstream/*
+```
+
+## Setup (one-time per repository)
+
+```powershell
+# Clone as bare into .bare/
+git clone --bare https://github.com/<owner>/<repo>.git .bare
+
+# Create the .git pointer file
+Set-Content .git "gitdir: ./.bare" -NoNewline
+
+# Configure fetch refspec (bare clones don't set this automatically)
+git -C .bare config remote.origin.fetch '+refs/heads/*:refs/remotes/origin/*'
+
+# Fetch remote branches
+git -C .bare fetch origin
+
+# Create the default branch worktree
+git -C .bare worktree add ../main main
+```
+
+> The [Checkout-GitHubRepo](https://github.com/MariusStorhaug/.dev/blob/main/.github/Checkout-GitHubRepo.ps1) script automates this for all repositories.
+
+## Working on an issue
+
+```powershell
+# From the repo root (where .bare/ lives)
+git -C .bare worktree add ../42-add-pagination -b 42-add-pagination main
+
+# Open in VS Code
+code 42-add-pagination
+```
+
+Then follow the normal Implement flow: initial commit → push → draft PR → build → finalize.
+
+## Cleanup after merge
+
+```powershell
+# Remove the worktree
+git -C .bare worktree remove 42-add-pagination
+
+# Prune if needed (removes stale worktree references)
+git -C .bare worktree prune
+```
+
+The sync script handles this automatically — worktrees whose branch no longer exists on any remote are removed during the next sync.
+
+## Parallel agents
+
+The worktree model enables multiple agents to work in the same repository at the same time:
+
+- Each agent operates in its own worktree (its own issue folder).
+- No merge conflicts during development — conflicts only surface at PR merge time.
+- The default branch worktree provides a stable reference for all agents to read from.
+- CI runs independently per PR, so agents don't block each other.
+
+```text
+Agent A: working in  42-add-pagination/
+Agent B: working in  43-fix-auth-flow/
+Human:   reviewing in main/ or reading docs
+```
+
+## VS Code integration
+
+- **Open the worktree folder directly** — VS Code's Git extension auto-detects the git context.
+- **Multi-root workspace** — add multiple worktrees to one window (`File → Add Folder to Workspace`) to reference `main/` while coding in another.
+- **Terminal cwd** — ensure the integrated terminal is in the worktree folder, not the bare root.
+
+## Rules
+
+1. **Never commit directly to the default branch worktree.** It exists for reference only.
+2. **One worktree per issue.** The folder name matches the branch name: `<N>-<slug>`.
+3. **Clean up after merge.** Remove the worktree and let the sync script prune stale branches.
+4. **All git config lives in `.bare/`** — it applies to every worktree automatically.
+5. **Only `origin` and `upstream` remotes.** No other remotes. `upstream` only exists for forks.

docs/Agents/Issue-Format.md

@@ -38,11 +38,11 @@ A clear, imperative-mood statement of the work. Not a question, not a symptom.
 
 The description has three sections separated by horizontal rules (`---`), ordered from behavioural to architectural to tactical. The user need is understood before the technical discussion.
 
-| Section | Owner          | Present in                                            |
-| ------- | -------------- | ----------------------------------------------------- |
-| 1 — Context and Request | Ideator → Clarifier   | Every issue at every level (Task, PBI, Epic) |
-| 2 — Technical Decisions | Planner               | Task always; PBI / Epic for decomposition rationale |
-| 3 — Implementation Plan | Planner               | Task always (task list); PBI / Epic (links to children) |
+| Section                   | Owner                 | Present in                                                    |
+| ------------------------- | --------------------- | ------------------------------------------------------------- |
+| 1 — Context and Request   | Ideator → Clarifier   | Every issue at every level (Task, PBI, Epic)                  |
+| 2 — Technical Decisions   | Planner               | Task always; PBI / Epic for decomposition rationale           |
+| 3 — Implementation Plan   | Planner               | Task always (task list); PBI / Epic (links to children)       |
 
 ## Section 1 — Context and Request
 

docs/Agents/Issue-Hierarchy.md

@@ -4,11 +4,11 @@ Work in PSModule is tracked at three levels. The level reflects **scope and aggr
 
 ## The three levels
 
-| Level                    | Issue type   | Scope                                              | Output                                                    |
-| ------------------------ | ------------ | -------------------------------------------------- | --------------------------------------------------------- |
-| **Task**                 | `Task`       | One deliverable. One small reviewable PR.          | Working software.                                          |
-| **Product Backlog Item** | `PBI`        | A body of work composed of multiple Tasks.         | Tracking, delegation, oversight, visibility into progress. |
-| **Epic**                 | `Epic`       | Strategic chunk needing multiple PBIs.             | The co-planning artifact. Where OKRs become initiatives.  |
+| Level                    | Issue type   | Scope                                              | Output                                                              |
+| ------------------------ | ------------ | -------------------------------------------------- | ------------------------------------------------------------------- |
+| **Task**                 | `Task`       | One deliverable. One small reviewable PR.          | Working software.                                                   |
+| **Product Backlog Item** | `PBI`        | A body of work composed of multiple Tasks.         | Tracking, delegation, oversight, visibility into progress.          |
+| **Epic**                 | `Epic`       | Strategic chunk needing multiple PBIs.             | The co-planning artifact. Where OKRs become initiatives.            |
 
 > The name **Product Backlog Item** is chosen for its neutral vibe — it works equally well for a feature, a fix, a refactor, or an internal capability. "Feature" implies user-visible value, which isn't always the case for the middle tier.
 
@@ -76,10 +76,10 @@ Text-level conventions on child issues:
 
 ## How the sections differ by level
 
-| Section                  | Task                          | PBI                                                                 | Epic                                                                 |
-| ------------------------ | ----------------------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------- |
-| Section 1 (Context/Req)  | The deliverable's user story  | The grouped goal's user story                                       | The strategic outcome — vision, why, the change in the world         |
-| Section 2 (Decisions)    | Implementation decisions      | Decomposition rationale + interface decisions between children      | Decomposition rationale + which PBIs and why                         |
+| Section                  | Task                          | PBI                                                                  | Epic                                                                 |
+| ------------------------ | ----------------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| Section 1 (Context/Req)  | The deliverable's user story  | The grouped goal's user story                                        | The strategic outcome — vision, why, the change in the world         |
+| Section 2 (Decisions)    | Implementation decisions      | Decomposition rationale + interface decisions between children       | Decomposition rationale + which PBIs and why                         |
 | Section 3 (Plan)         | Checkbox task list            | Linked list of child issues (Tasks and/or sub-PBIs)                  | Linked list of child PBIs                                            |
 
 For Epics, Section 1 should explicitly contain the **Golden Circle framing**: Why, How, What. See [Principles → Golden Circle](Principles.md#start-with-why--the-golden-circle).