# 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.