Add documentation site; refocus README and CONTRIBUTING; fix image tags and CI paths

- docs/: VitePress documentation site (overview, architecture, backend,
  frontend, operations, getting-started install/configuration, bundling, and
  development) with Mermaid diagrams and per-page Markdown for assistants, plus a
  GitHub Pages deploy workflow.
- README: slimmed to a pitch that points at the docs.
- CONTRIBUTING: contribution norms and DCO sign-off; development setup moved to
  the docs.
- Issue template: drop the duplicate security-reporting entry.
- CI: tag images :staging on non-release builds and reserve :latest for releases;
  skip the test and image workflow on docs-only changes.
- AGENTS.md: documentation rules and a contribution-verification workflow.

Author: Akarithos

.github/ISSUE_TEMPLATE/config.yml

@@ -3,6 +3,3 @@ contact_links:
   - name: Ask a setup question
     url: https://github.com/Ident-1090/Ident/discussions
     about: Use Discussions for install help, receiver setup questions, and general support.
-  - name: Report a security vulnerability
-    url: https://github.com/Ident-1090/Ident/security/advisories/new
-    about: Please report security issues privately.

.github/workflows/ci.yml

@@ -2,11 +2,23 @@ name: CI
 
 on:
   pull_request:
+    paths-ignore:
+      - "docs/**"
+      - "**/*.md"
+      - ".gitignore"
+      - ".github/ISSUE_TEMPLATE/**"
+      - ".github/workflows/docs.yml"
   push:
     branches:
       - main
     tags:
       - "v*"
+    paths-ignore:
+      - "docs/**"
+      - "**/*.md"
+      - ".gitignore"
+      - ".github/ISSUE_TEMPLATE/**"
+      - ".github/workflows/docs.yml"
   workflow_dispatch:
     inputs:
       version:
@@ -425,15 +437,16 @@ jobs:
           images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
           tags: |
             type=raw,value=${{ needs.metadata.outputs.version }},enable=${{ needs.metadata.outputs.is_release == 'true' }}
-            type=raw,value=latest
+            type=raw,value=latest,enable=${{ needs.metadata.outputs.is_release == 'true' }}
+            type=raw,value=staging,enable=${{ needs.metadata.outputs.is_release != 'true' }}
       - name: Create manifest list and push
         id: manifest
         working-directory: /tmp/digests
         run: |
           docker buildx imagetools create \
             $(jq -cr '.tags | map("-t " + .) | join(" ")' <<< "$DOCKER_METADATA_OUTPUT_JSON") \
             $(printf '${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}@sha256:%s ' *)
-          digest="$(docker buildx imagetools inspect ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest --format '{{json .Manifest.Digest}}' | tr -d '"')"
+          digest="$(docker buildx imagetools inspect ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ steps.meta.outputs.version }} --format '{{json .Manifest.Digest}}' | tr -d '"')"
           echo "digest=$digest" >> "$GITHUB_OUTPUT"
       - name: Attest container image
         uses: actions/attest-build-provenance@v4

.github/workflows/docs.yml

@@ -0,0 +1,54 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment; let an in-progress run finish.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: docs
+    steps:
+      - uses: actions/checkout@v6
+      - uses: pnpm/action-setup@v6
+        with:
+          version: 10.29.2
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          cache: pnpm
+          cache-dependency-path: docs/pnpm-lock.yaml
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm docs:build
+        env:
+          DOCS_BASE: /Ident/
+      - uses: actions/configure-pages@v5
+      - uses: actions/upload-pages-artifact@v4
+        with:
+          path: docs/.vitepress/dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/deploy-pages@v4
+        id: deployment

.gitignore

@@ -20,6 +20,11 @@ identd/web/*
 # Generated receiver fixture output.
 fixtures/receiver-sample/
 
+# Documentation site.
+docs/node_modules/
+docs/.vitepress/dist/
+docs/.vitepress/cache/
+
 # Local working instructions for this release-prep checkout.
 CLAUDE.local.md
 AGENTS.override.md

AGENTS.md

@@ -21,22 +21,44 @@ Use placeholders such as `receiver.local`, `YOUR_LAT`, `YOUR_LON`, and
 
 ## Documentation Rules
 
+The repository has a documentation site under `docs/`. Every change must keep it
+true. This is not optional: before a change is finished, verify the doc pages that
+describe the affected area still match the code, and update them in the same
+change whenever behavior, design, configuration, install shape, interfaces, or
+network access move. A change that leaves a doc page wrong is not complete until
+the page is fixed. The writing conventions for the site, including how to verify
+claims against the code, live in `docs/AGENTS.md`.
+
 - Write for receiver owners first, then add technical detail.
 - Keep install commands minimal and copyable.
 - Mention optional network access when a feature calls outside the receiver.
 - Do not compare Ident directly to other projects in public docs.
 - Keep examples generic enough for readsb, ultrafeeder, dump1090-fa, and
   PiAware users. Use stack-specific examples only in stack-specific sections.
 
+### Docs as the plan
+
+The docs are the design surface for a change, not an afterthought written at the
+end. The lifecycle is:
+
+- In the plan phase, write the doc for the change first, as the design. A human
+  reads that doc as the plan and reviews it before the work proceeds.
+- While the work is in progress, the doc may carry a task breakdown or todo list
+  for that change, so the plan and the work stay in one place.
+- At delivery, none of that may remain. The published docs are camera-ready: no
+  todo lists, no task breakdowns, no "planned" or "in progress" scaffolding. They
+  describe what exists. Track unfinished follow-ups outside the published docs.
+
 ## Development Rules
 
 - Keep changes focused.
 - Add tests for behavior changes.
 - Weigh per-frame and render-path cost. Prefer identity-stable selector
   outputs, avoid hot-loop allocations, and skip imperative updates (`setData`,
   GPU uploads) when inputs are unchanged.
-- Update docs when configuration, install shape, privacy behavior, or network
-  access changes.
+- Every change includes documentation verification and update: confirm the docs
+  for the affected area still match, and update them in the same change. See the
+  Documentation Rules above.
 - Do not choose or change the project license without maintainer approval.
 
 ## State and Data Rules

CONTRIBUTING.md

@@ -1,181 +1,55 @@
 # Contributing to Ident
 
 Ident is built for people running their own ADS-B receivers. Good contributions
-keep that audience in mind: the app should be understandable for receiver
-owners, predictable for operators, and straightforward to install on common
-receiver hosts.
+keep that audience in mind: the app should be understandable for receiver owners,
+predictable for operators, and straightforward to install on common receiver
+hosts.
 
-## Before You Open an Issue
+By participating, you agree to abide by the [Code of Conduct](CODE_OF_CONDUCT.md).
 
-Search existing issues and discussions first. If the problem is a security
-issue, do not open a public issue; use the private reporting link in
-[SECURITY.md](SECURITY.md).
+## Reporting issues
 
-Please do not include private station details in public issues.
+Search the existing issues and discussions first. For a security issue, do not
+open a public issue; use
+[private vulnerability reporting](https://github.com/Ident-1090/Ident/security/advisories/new).
 
-Avoid sharing:
+Do not include private station details in public issues: feeder keys or claim
+tokens, exact receiver coordinates, home or location hints, private hostnames or
+tunnel URLs, or screenshots that reveal where you are. Use placeholders such as
+`receiver.local`, `YOUR_LAT`, `YOUR_LON`, and `YOUR_FEEDER_ID`.
 
-- feeder keys or claim tokens
-- exact receiver coordinates
-- home address or location hints
-- private hostnames, tunnel URLs, or local network names
-- screenshots that reveal private location details
+For install and compatibility reports, include the Ident version, your decoder and
+where it writes `aircraft.json`, which optional files exist (`receiver.json`,
+`stats.json`, `outline.json`), the operating system and hardware, the install
+method, the browser and device used for the UI, and any relevant `identd` logs.
+For UI issues, crop or redact screenshots that reveal your location.
 
-Use placeholders such as `receiver.local`, `YOUR_LAT`, `YOUR_LON`, and
-`YOUR_FEEDER_ID` when an example needs a value.
+## Pull requests
 
-## Good Bug Reports
+Keep pull requests focused. A small change with clear behavior, tests, and docs is
+easier to review than a broad change that mixes unrelated work.
 
-For install and compatibility issues, include:
+- Include tests for behavior changes.
+- Update the docs when install, configuration, network access, or user-facing
+  behavior changes.
+- Do not add a new external service without documenting the network access.
+- Do not add station-specific examples or private deployment assumptions.
+- Keep receiver data read-only by default; document and justify any write path.
 
-- Ident version
-- receiver JSON source: readsb native, dump1090-fa native including PiAware, or
-  dump978-fa native including SkyAware978
-- operating system and hardware model
-- install method: binary, Docker, systemd, Debian package, or source
-- path where `aircraft.json` is written
-- which optional files exist, such as `receiver.json`, `stats.json`, or
-  `outline.json`
-- browser and device used for the UI
-- relevant `identd` logs
+For local setup, builds, the checks to run, and the pre-commit hook, see the
+[Development guide](https://ident-1090.github.io/Ident/development).
 
-For UI issues, screenshots are useful. Crop or redact anything that reveals a
-private receiver location.
+## Developer Certificate of Origin
 
-## Pull Requests
-
-Keep pull requests focused. A small change with clear behavior, tests, and docs
-is easier to review than a broad change that mixes unrelated work.
-
-Expected baseline:
-
-- include tests for behavior changes
-- update docs when install, configuration, network access, or user-facing
-  behavior changes
-- avoid introducing new external services without documenting network access
-- do not add station-specific examples or private deployment assumptions
-- keep receiver data read-only by default; document and justify any write path
-
-Before opening a pull request, run the checks that apply to your change.
-
-```sh
-cd ident
-pnpm test
-pnpm build
-
-cd ../identd
-go test ./...
-```
-
-If you cannot run a relevant check, say which check you skipped and why.
-
-### Wire Schemas
-
-Ident-owned WebSocket and HTTP payload schemas live in `schemas/ident/`. They
-are generated from the Go wire structs with `github.com/google/jsonschema-go`.
-
-Refresh schemas after changing a wire struct:
+Contributions are accepted under the
+[Developer Certificate of Origin](https://developercertificate.org/) (DCO). It
+certifies that you wrote the contribution, or otherwise have the right to submit
+it under the project's license. You agree to it by signing off each commit:
 
 ```sh
-cd identd
-IDENT_UPDATE_SCHEMAS=1 go test . -run TestIdentSchemasAreCurrent -count=1
-go test . -run TestIdentSchemasAreCurrent -count=1
+git commit -s
 ```
 
-The normal Go test fails when a committed schema is stale, so CI and the local
-pre-commit hook both enforce freshness.
-
-### Pre-commit hook
-
-The hook lives at `ident/.husky/pre-commit` and runs three checks: `gofmt`
-against `identd/`, `pnpm check-ident-schemas` (the schema-freshness check
-above), and `pnpm exec lint-staged` (biome formatting of staged JS/TS/JSON).
-Husky installs the hook from `ident/package.json`'s `prepare` script, so you
-need to have run `pnpm install` inside `ident/` at least once for the hook to
-fire. If your commit fails with "gofmt would rewrite", run `gofmt -w identd/`
-and re-stage.
-
-## Development Notes
-
-The release architecture is:
-
-- `ident/`: React web UI
-- `identd/`: Go service and embedded release binary
-- `packaging/`: Docker, systemd, and package assets
-
-Development can run the frontend and service separately. Release builds embed
-the web UI into `identd`.
-
-### Internal configuration
-
-These environment variables exist for development, testing, and operator
-overrides. They are intentionally kept out of the user-facing README so the
-common installation flow stays short.
-
-- `IDENT_RELAY_ROUTE_UPSTREAM` — base URL of the airline route lookup
-  service (default: `https://adsb.im/api/0/routeset`)
-- `IDENT_RELAY_ROUTE_TTL_SEC` — how long Ident caches a successful route
-  lookup before re-querying (default: 5 minutes)
-- `IDENT_RELAY_ROUTE_BATCH_MS` — debounce window for coalescing per-callsign
-  lookups into one upstream request (default: 250 ms)
-- `IDENT_UPDATE_API_URL` — GitHub-style releases endpoint Ident polls for
-  update checks (default: `https://api.github.com`)
-- `IDENT_UPDATE_TIMEOUT_SEC` — HTTP timeout for a single update check
-  (default: 10 s)
-
-### Diagnostics
-
-`identd` keeps diagnostics in a TTL-backed store in `identd/diagnostics.go`.
-Identity is `(channel, code, scope)` — re-emitting with the same identity
-refreshes the entry's TTL and updates mutable fields (severity, message,
-action) without producing a duplicate. The store publishes the full snapshot
-on the `ident.diagnostics.v1` channel; the frontend replaces its local set
-each time.
-
-Operationally relevant behaviors:
-
-- Capacity is bounded (200 entries by default). When the cap is reached, the
-  oldest entry is evicted, the eviction is logged with `slog.Warn`
-  (`diagnostics: cap reached, dropping oldest`, attributes `channel`, `code`,
-  `scope`, `severity`, `ageSec`), and the store publishes a self-describing
-  `diagnostics.store.capacity_exceeded` warning so the UI also shows the
-  saturation.
-- TTLs are picked at the emission site. Sustained conditions re-emit on a
-  poll cadence and refresh their TTL; transient events use a 5-minute
-  visibility window; persistent notices use `WithTTL(0)` and stay until
-  process restart.
-- Receiver-derived conditions (producer not classifiable, upstream-type
-  override mismatch) re-emit every 5 minutes from
-  `ReemitReceiverConditions` in `identd/producer_status.go` so a static but
-  misconfigured `receiver.json` doesn't let the diagnostic age out of the
-  15-minute window.
-
-### Capability gating
-
-`ident.capabilities.v1` reports which fields the current producer can supply
-(`producer_provided`, `ident_derived`, or `unavailable`). The status bar omits
-rows whose capability is `unavailable` rather than rendering them blank.
-Observed capabilities are sticky across receiver reingest with the same
-producer kind, and reset on a producer-kind transition — the merge rule is in
-`producer_status.go:mergeStrongerCapabilities`. The intent is to avoid row
-flicker when a single sample is missing a field; downgrade only happens when
-the producer itself changes.
-
-### Wire schemas
-
-The eight Ident-owned wire envelopes are generated under `schemas/ident/`:
-`ident.aircraft.v1`, `ident.status.v1`, `ident.capabilities.v1`,
-`ident.diagnostics.v1`, `ident.rangeOutline.v1`, `ident.config.v1`,
-`ident.routes.v1`, `ident.replay.availability.v1`. The `Refresh schemas after
-changing a wire struct` section above is the source of truth for regenerating
-them.
-
-## Documentation Style
-
-Write for receiver owners first, then add the technical detail maintainers need.
-
-- prefer concrete receiver workflows over abstract feature language
-- use placeholders for station-specific values
-- mention when a feature depends on an optional file or outside service
-- keep install commands minimal and copyable
-- do not compare Ident directly to other projects in public docs
+This adds a `Signed-off-by: Your Name <you@example.com>` line to the commit
+message, using the name and email from your Git configuration. The full
+certificate is at <https://developercertificate.org/>.