docs: add HardenedPass docs section design

Wiki-like bilingual section on the site, with a shared page tree, one
reading order across sections and collapsible navigation on mobile.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

1 files changed, 113 insertions, 0 deletions

diff --git a/docs/superpowers/specs/2026-11-05-hardenedpass-docs-design.md b/docs/superpowers/specs/2026-11-05-hardenedpass-docs-design.md
new file mode 100644
index 0000000..d81e177
--- /dev/null
+++ b/docs/superpowers/specs/2026-11-05-hardenedpass-docs-design.md
@@ -0,0 +1,113 @@
+# HardenedPass docs section: design
+
+## Goal
+
+Document the HardenedPass Android app on danix.xyz in a wiki-like section: what it
+is, how it works, how to do things with it. Readers include complete beginners who
+have never used `pass`, OpenPGP or git. Only the maintainer writes pages, so no
+in-browser editing is needed, and a subdomain with wiki software was rejected.
+
+## Location
+
+New top-level section, bilingual: `/hardenedpass/` and `/it/hardenedpass/`. Menu
+entry in both languages directly after `slackware`; `legal` moves to weight 7.
+
+## Page tree
+
+Eleven pages, three section indexes and the landing page, in EN and
+IT. Each page has a unique `weight` that sets one reading order across all sections.
+
+| Path | Weight | Covers |
+|---|---|---|
+| `_index` | | What it is, why the fork exists, what differs from upstream |
+| `getting-started/concepts` | 10 | pass, OpenPGP and git in plain words, and each one's role |
+| `getting-started/install` | 20 | Get the APK, verify checksum and signing certificate, update |
+| `getting-started/create-store` | 30 | From zero: PGP key, store, private git remote |
+| `getting-started/connect` | 40 | Clone on the phone, SSH key or password, import PGP key |
+| `using/entries` | 50 | Read, search, copy, create, edit, move, delete, generator |
+| `using/otp` | 60 | TOTP codes |
+| `using/sync` | 70 | Pull, push, conflicts and recovery |
+| `using/autofill` | 80 | Enable, fill, save, phishing warning, browsers |
+| `reference/settings` | 90 | Every setting and what it does |
+| `reference/security` | 100 | Where secrets live, what the app protects from and what it does not |
+| `reference/troubleshooting` | 110 | Common errors, their meaning, the fix |
+
+`getting-started` reads in order. A reader who already has a store starts at
+`connect`. No FAQ page (it lives in `troubleshooting`), no changelog (GitHub Releases
+has it), no build-from-source page (the README has it).
+
+## Layout
+
+Desktop, from the theme's `lg` breakpoint (1060px): a sticky left column holds the
+page tree and, below it, the current page's table of contents. The right column
+holds breadcrumb, title, content and prev/next links.
+
+Mobile: the tree and the table of contents collapse into two native `<details>`
+elements above the content. No JavaScript.
+
+Prev/next walk `RegularPagesRecursive.ByWeight` of the section, because
+`.PrevInSection` stops at section borders. Section index pages list their own pages.
+`project-row` is not reused: it is built for projects with status badges.
+
+## Search
+
+Site search indexes title and the first 160 characters of the summary, not body
+text. The section is added to `index.json` as is. Every page therefore needs a
+`date`, which the index prints, and a summary that names its topic. Full-text search
+would change search site-wide and is out of scope.
+
+## Changes
+
+Theme repo (`themes/danix-xyz-hacker`):
+
+- `layouts/hardenedpass/list.html`, `layouts/hardenedpass/single.html`
+- `layouts/partials/docs-nav.html`: tree, table of contents, prev/next
+- `layouts/index.json`: add the section
+- Tailwind utilities only, then `npm run build` to refresh `main.min.css`
+
+Content repo:
+
+- `hugo.toml`: menu entries for both languages
+- `i18n/en.yaml`, `i18n/it.yaml`: new keys
+- `content/{en,it}/hardenedpass/`
+- `static/uppies/2026/11/`: banner and screenshots
+- Submodule pointer bump
+
+HardenedPass repo, once the section is live: link the docs from the README and remove
+the website item from `TODO.md`.
+
+## Content rules
+
+- Voice: first-person site tone on the landing page only. How-tos use plain second
+  person.
+- Both languages are drafted together; the maintainer reviews the Italian.
+- Every step is checked against the code or on the emulator before it is written.
+  Nothing is carried over from upstream docs unverified.
+- Values that drift, such as dependency versions, stay out of the pages.
+- Examples use example.org addresses and placeholder hostnames.
+
+## Screenshots
+
+Taken from the `aps-test` emulator running windowed, with the throwaway e2e store
+only, in both languages. The agent drives the emulator and says what to capture; the
+maintainer takes each screenshot from the host. `FLAG_SECURE` blocks `screencap`, not
+the emulator window, so secure screens are expected to be capturable this way; the
+first such capture confirms it. If it fails, those screens stay text only.
+
+## Verification
+
+- `hugo --gc --minify` builds clean with `relref` for internal links, so a broken
+  link fails the build.
+- Local `hugo server -D` checked at desktop and mobile widths, in both languages.
+
+## Publishing
+
+All pages start with `draft = true`. The maintainer flips them after review and
+merges `master` into `production` to deploy. The agent never touches `production`.
+
+## Order of work
+
+1. Theme, layouts and menu, with placeholder pages.
+2. `getting-started`, for review.
+3. `using`, for review.
+4. `reference` and the landing page, for review.