Skip to content

Commit a9eef6d

Browse files
hyperpolymathclaude
hyperpolymath
and
claude
committed
docs: adopt docs-template/ skeleton (architecture/usage/contributing/troubleshooting + ADR)
Closes Row-2 Phase 2 of the 2026-05-26 estate tech-debt audit chain for this repo. The 2026-05-26 documentation-debt audit (hyperpolymath/standards#197) flagged this repo as MEDIUM doc-debt: substantial top-level README but no docs/ tree. This PR seeds docs/ with the canonical 4-section + ADR skeleton from hyperpolymath/rsr-template-repo#75: - docs/architecture.adoc (system overview, components, invariants) - docs/usage.adoc (consumer perspective) - docs/contributing.adoc (developer perspective) - docs/troubleshooting.adoc (FAQ-style) - docs/decisions/0001-template.adoc (ADR template) Placeholders ({{PROJECT_NAME}}, etc.) have been substituted to this repo's actual values. The skeleton structure is canonical; the substantive content is owed to the maintainer. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 0723a77 commit a9eef6d

5 files changed

Lines changed: 359 additions & 0 deletions

File tree

‎docs/architecture.adoc‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
// SPDX-License-Identifier: MPL-2.0
2+
// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) <6759885+hyperpolymath@users.noreply.github.com>
3+
= Architecture — hyperpolymath.github.io
4+
:revdate: 2026-MM-DD
5+
6+
== System overview
7+
8+
One paragraph: what this project does and what it does not do. State the
9+
*invariant* — the property that, if violated, would make the whole project
10+
pointless. Future maintainers will read this paragraph first.
11+
12+
== Component diagram
13+
14+
Replace this section with an ASCII or Mermaid diagram. Keep it under 20
15+
lines — anything bigger belongs in `architecture/`.
16+
17+
[source]
18+
----
19+
+------------------+ +------------------+
20+
| Component A | ---> | Component B |
21+
+------------------+ +------------------+
22+
|
23+
v
24+
+------------------+
25+
| Component C |
26+
+------------------+
27+
----
28+
29+
== Data flow
30+
31+
For each external input, describe:
32+
33+
* **Source**: where it comes from.
34+
* **Validation**: what guarantees we enforce on entry.
35+
* **Transformation**: high-level processing stages.
36+
* **Sink**: where the result goes.
37+
38+
== Key invariants
39+
40+
Enumerate the load-bearing invariants of the system. Each should have:
41+
42+
. A one-line statement.
43+
. The code location(s) that enforce it.
44+
. The failure mode if the invariant is violated.
45+
46+
Example:
47+
48+
[cols="1,2,2,2", options="header"]
49+
|===
50+
| # | Invariant | Enforced at | Failure mode
51+
52+
| 1
53+
| All HTTP requests carry a valid `X-Request-ID`.
54+
| `src/middleware/request_id.rs`
55+
| Logs become unjoinable; correlation breaks.
56+
57+
| 2
58+
| The output buffer is always flushed before exit.
59+
| `src/main.rs:88-92` (Drop impl)
60+
| Last ~16KB of log lost on crash.
61+
|===
62+
63+
== Dependencies
64+
65+
* **Internal**: list other hyperpolymath repos this depends on.
66+
* **External**: SHA-pinned (see `Cargo.lock` / `deno.lock` / etc.).
67+
* **Build-time**: tools required to build (just, deno, cargo, …).
68+
69+
== Out of scope
70+
71+
Explicit non-goals. Things we deliberately do *not* do, with a one-line
72+
reason for each. This section saves more time than the rest combined.
73+
74+
== See also
75+
76+
* link:./usage.adoc[Usage] — consumer perspective.
77+
* link:./contributing.adoc[Contributing] — developer setup.
78+
* link:./decisions/[ADRs] — historical record of why this shape.

‎docs/contributing.adoc‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
// SPDX-License-Identifier: MPL-2.0
2+
// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) <6759885+hyperpolymath@users.noreply.github.com>
3+
= Contributing — hyperpolymath.github.io
4+
:revdate: 2026-MM-DD
5+
6+
== Audience
7+
8+
Developers working *on* `hyperpolymath.github.io`. For consumers (people calling
9+
or depending on it) see link:./usage.adoc[usage.adoc].
10+
11+
== Local-dev setup
12+
13+
Prerequisites — the minimum versions and where to get them:
14+
15+
* `<tool 1>` v`<version>` — `<install instruction>`.
16+
* `<tool 2>` v`<version>` — `<install instruction>`.
17+
* GPG signing key configured (estate policy — all commits must be
18+
signed). See
19+
link:https://github.com/hyperpolymath/standards/blob/main/docs/secure-coding-training.md[standards/docs/secure-coding-training.md].
20+
21+
One-shot setup:
22+
23+
[source,bash]
24+
----
25+
git clone git@github.com:hyperpolymath/hyperpolymath.github.io.git
26+
cd hyperpolymath.github.io
27+
just setup # installs deps, sets up hooks
28+
just test # runs the full test suite
29+
----
30+
31+
== Running tests
32+
33+
* **Unit**: `just test-unit` — fast, no I/O.
34+
* **Integration**: `just test-int` — uses real services (database,
35+
HTTP, etc.). Estate policy: prefer real over mocked
36+
(see `feedback_integration_tests_real_db` in maintainer's memory).
37+
* **Property**: `just test-prop` — randomised, slower; budget
38+
documented in `docs/proof-debt.md` if applicable.
39+
* **Full**: `just test` — runs all of the above.
40+
41+
== Code style
42+
43+
We enforce style via CI (governance-reusable.yml from hyperpolymath/standards).
44+
Locally:
45+
46+
[source,bash]
47+
----
48+
just fmt # auto-format
49+
just lint # static checks
50+
----
51+
52+
* All commits must be **GPG-signed** (CI enforces; see
53+
link:https://github.com/hyperpolymath/standards[standards]).
54+
* All source files must carry an **SPDX-License-Identifier** header
55+
(CI enforces).
56+
* Conventional commits — `feat`, `fix`, `chore`, `refactor`, `docs`,
57+
`test`, `ci`, `revert` (CHANGELOG is auto-generated from these
58+
via link:https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml[`changelog-reusable.yml`]).
59+
60+
== Branching & PR workflow
61+
62+
. Branch off `main` as `claude/<topic>` (for AI agents) or
63+
`<initials>/<topic>` (for humans).
64+
. Make focused, narrow commits — one logical change per commit.
65+
. Open a PR against `main`.
66+
. **Enable auto-merge immediately** on every PR you open
67+
(`gh pr merge <num> --auto --squash`) — estate standing policy
68+
(see standards#196 audit and policies).
69+
. CI must be green. The PR auto-merges when checks pass + reviews land.
70+
71+
== Adding a new dependency
72+
73+
. State the *why* in the PR body — what does this dependency unlock?
74+
. Check provenance (maintained, audited, no malicious history).
75+
. Pin to a SHA, not a tag.
76+
. Update `docs/architecture.adoc#Dependencies`.
77+
78+
== Adding an ADR
79+
80+
When you make a non-obvious design decision, write it down:
81+
82+
. Copy `docs/decisions/0001-template.adoc` → `0002-<slug>.adoc`.
83+
. Fill in: Context, Decision, Consequences, Alternatives.
84+
. Link the ADR from the README or relevant code as a comment.
85+
86+
== Reporting issues
87+
88+
* Bugs in `hyperpolymath.github.io`: file at `hyperpolymath/hyperpolymath.github.io/issues`.
89+
* Estate-wide concerns (policy, conventions, CI): file at
90+
`hyperpolymath/standards/issues`.

‎docs/decisions/0001-template.adoc‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
// SPDX-License-Identifier: MPL-2.0
2+
// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) <6759885+hyperpolymath@users.noreply.github.com>
3+
= ADR-0001 — Use Architecture Decision Records
4+
:revdate: 2026-MM-DD
5+
:status: ACCEPTED
6+
7+
== Context
8+
9+
We need a lightweight way to record significant architectural decisions
10+
and the reasoning behind them, so future maintainers (and AI agents)
11+
can understand *why* the project is shaped as it is.
12+
13+
== Decision
14+
15+
Adopt link:https://adr.github.io/[Architecture Decision Records (ADRs)]
16+
in `docs/decisions/`, numbered sequentially (0001, 0002, ...).
17+
18+
* Each ADR is a single `.adoc` file.
19+
* The first ADR (this one) records the decision to use ADRs.
20+
* Status values: PROPOSED, ACCEPTED, DEPRECATED, SUPERSEDED.
21+
* When a decision is overturned, the new ADR records the supersession
22+
and updates the old one's status to `SUPERSEDED by 00NN`.
23+
24+
== Consequences
25+
26+
. **Positive**: future readers see *why* without git-archaeology.
27+
. **Positive**: design alternatives are documented, not just the
28+
winning choice.
29+
. **Positive**: ADRs are reviewable in PRs — the design discussion
30+
happens alongside the code that implements it.
31+
. **Negative**: maintenance burden — every non-obvious decision now
32+
warrants an ADR. (We mitigate by keeping ADRs short; "non-obvious"
33+
is a judgment call.)
34+
. **Negative**: ADRs can rot. We accept this; the SUPERSEDED chain
35+
is the recovery mechanism.
36+
37+
== Alternatives considered
38+
39+
. **Comments in code** — too local; doesn't capture cross-cutting
40+
decisions.
41+
. **Wiki / external doc** — drifts from code; not in PR review.
42+
. **Commit messages** — too transient and not discoverable.
43+
. **No record** — discarded; this is how every project ends up with
44+
"I don't know why we do it this way" debt.
45+
46+
== Companion ADRs
47+
48+
* (None yet — this is the first ADR.)
49+
50+
== References
51+
52+
* MADR template — `https://adr.github.io/madr/`
53+
* Estate convention — `hyperpolymath/standards/docs/RSR_OUTLINE.adoc`

‎docs/troubleshooting.adoc‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
// SPDX-License-Identifier: MPL-2.0
2+
// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) <6759885+hyperpolymath@users.noreply.github.com>
3+
= Troubleshooting — hyperpolymath.github.io
4+
:revdate: 2026-MM-DD
5+
6+
This file is a *living FAQ* — known failure modes and recovery paths.
7+
Add a new entry every time you debug something that took more than 15
8+
minutes; future-you (and other maintainers) will thank you.
9+
10+
== Known failure modes
11+
12+
=== `<error message or symptom>`
13+
14+
**Symptom**: short reproduction. What does the user see?
15+
16+
**Cause**: root cause (one or two sentences).
17+
18+
**Fix**:
19+
[source,bash]
20+
----
21+
<the actual commands to recover>
22+
----
23+
24+
**Avoidance**: how to not hit this again (config setting, doc link, etc.).
25+
26+
---
27+
28+
=== `<another failure mode>`
29+
30+
(Replace this and the above example with real entries as you encounter
31+
them.)
32+
33+
== Diagnostic toolkit
34+
35+
When something is wrong, run these first:
36+
37+
[source,bash]
38+
----
39+
just doctor # runs all available self-checks
40+
just version # prints the version & build hash
41+
just log-tail # last N lines of logs
42+
----
43+
44+
== When to escalate
45+
46+
. Filed an issue with: version, OS, exact command, full error output,
47+
and the symptom in plain English.
48+
. Linked from the issue: the relevant ADR(s) and any related issues.
49+
. For *security*-relevant findings, see
50+
link:./../SECURITY.md[SECURITY.md] — do **not** file public issues.
51+
52+
== Where to look for more help
53+
54+
* `docs/architecture.adoc` — internals.
55+
* `docs/decisions/` — historical record of why things are this shape.
56+
* `https://github.com/hyperpolymath/hyperpolymath.github.io/issues?q=is%3Aissue+<your symptom>` — has anyone hit this before?
57+
* `https://github.com/hyperpolymath/standards/issues` — for estate-wide problems.

‎docs/usage.adoc‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
// SPDX-License-Identifier: MPL-2.0
2+
// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) <6759885+hyperpolymath@users.noreply.github.com>
3+
= Usage — hyperpolymath.github.io
4+
:revdate: 2026-MM-DD
5+
6+
== Audience
7+
8+
This document is for *consumers* of `hyperpolymath.github.io` — people who depend
9+
on it, call it, or include it. For developers working *on* it, see
10+
link:./contributing.adoc[contributing.adoc].
11+
12+
== Quickstart
13+
14+
The shortest path from zero to a working call:
15+
16+
[source,bash]
17+
----
18+
# 1. Install
19+
just install # or: cargo install --path . / deno task install
20+
21+
# 2. Configure
22+
cp examples/config.example.toml ./config.toml
23+
# Edit minimal required fields.
24+
25+
# 3. Run
26+
just run # or the equivalent for your language
27+
----
28+
29+
Expected output:
30+
31+
[source]
32+
----
33+
hyperpolymath.github.io v0.0.0
34+
Listening on 127.0.0.1:8080
35+
----
36+
37+
== Common use cases
38+
39+
For each canonical use case, give:
40+
41+
. A one-line statement of the goal.
42+
. The minimal invocation.
43+
. Expected output / side effect.
44+
45+
=== Use case 1: <short title>
46+
47+
(Replace with real content.)
48+
49+
=== Use case 2: <short title>
50+
51+
== Configuration reference
52+
53+
Document every configurable field. Keep this section authoritative — if
54+
the code grows a new option, this table must grow too (CI can be wired
55+
to enforce this).
56+
57+
[cols="1,1,1,3", options="header"]
58+
|===
59+
| Field | Type | Default | Meaning
60+
61+
| `<key>` | `<type>` | `<default>` | <what it does>
62+
|===
63+
64+
== Stability guarantees
65+
66+
Be explicit:
67+
68+
* **Stable**: API surfaces that follow SemVer (breaking change = major bump).
69+
* **Unstable**: behind a flag / pre-1.0 / explicitly marked.
70+
* **Internal**: documented for reference but no compatibility promise.
71+
72+
== Limits & known constraints
73+
74+
* Maximum supported `<X>`: `<value>`.
75+
* `<Y>` is not yet implemented; track at issue `#<n>`.
76+
* On `<platform>`, `<Z>` behaves differently because `<reason>`.
77+
78+
== See also
79+
80+
* link:./architecture.adoc[Architecture] — how it works internally.
81+
* link:./troubleshooting.adoc[Troubleshooting] — when things go wrong.

0 commit comments

Comments
 (0)