Generated from HELIX docs. Source:docs/helix/02-design/adrs/ADR-002-microsite-ia.md. Edit the source, not this file orsite/HTML.
Source frontmatter
ddx:
id: innsigle.adr.002
type: adr
links:
- target: innsigle.prd
kind: informed_by
- target: innsigle.design-system
kind: informed_by
status: accepted
activity: 02-design
created: 2026-07-23
ADR-002: Microsite information architecture and content pipeline
| Date | Status | Deciders | Related | Confidence |
|---|---|---|---|---|
| 2026-07-23 | Accepted | Operator | product-microsite-ia concern; PRD brand site FRs | High |
Context
| Aspect | Description |
|---|---|
| Problem | Public site mixed hand HTML with specs; HELIX concern requires reader-mode IA and generated reference from artifact sources |
| Requirements | Auto-publish walkthroughs/specs/design docs/glossary from docs/; keep carefully curated copy outside the HELIX source tree (docs/helix/) |
| Drivers | product-microsite-ia; DESIGN.md voice; dual UC evaluate/start/operate paths |
Decision
We will use a two-layer content model:
- Curated product copy under
docs/website/content/curated/(outside
docs/helix/). Hand-authored Why / Use / Non-goals pages for evaluate and start reader modes.
- Generated reference under
docs/website/content/generated/, rebuilt
deterministically from docs/helix/ (and glossary sources) by scripts/publish-artifacts.mjs.
- Build HTML into
site/viascripts/build-site.mjsusing DESIGN.md tokens
and IA from docs/website/ia.yml.
- Top-level nav separates: What it is (home) · Why · Use · Reference · Sample.
Key points: Curated ≠ generated | site/ is output only | HELIX sources remain authoritative for specs
Alternatives
| Option | Pros | Cons | Evaluation |
|---|---|---|---|
Hand-only static HTML in site/ | Simple | Specs drift; violates microsite concern | Rejected |
| Full Hugo/Hextra like HELIX | Mature | Heavy for v0; dependency burden | Deferred |
| Curated MD + generate artifacts → static build | Matches concern; light deps | Custom builder | Selected |
Consequences
| Type | Impact |
|---|---|
| Positive | Specs stay in docs/helix/; site always regenerable; IA named by reader mode |
| Negative | Must run publish+build before deploy |
| Neutral | Sample and marks still synced as static assets |
Risks
| Risk | Prob | Impact | Mitigation |
|---|---|---|---|
| Hand-edit generated HTML | M | M | Wipe site/ content pages on build; README warnings |
| Nav hides core leaves | L | H | ia.yml core_leaves + concern quality gates |
Validation
| Success Metric | Review Trigger |
|---|---|
npm run site:build produces Why/Use/Reference + artifact pages | IA change |
| Generated artifact index groups by activity | HELIX tree reorg |
Supersession
- Supersedes: None
- Superseded by: None
Concern Impact
- Satisfies product-microsite-ia ADR requirement (IA model + content pipeline).
- Updates
concerns.mdpractice for generated vs curated roots.
References
docs/website/ia.yml- HELIX
workflows/concerns/product-microsite-ia/ - HELIX
scripts/publish-artifacts.py(pattern source)
Innsigle seal: model-primary by Innsigle (build key)
Signature covers the markdown source of this page, not these HTML bytes. This render quotes that seal.
- Composition
- model-primary
- Issuer
- Innsigle
innsigle - Signing key
ed25519:050bf4d0361a96aa3b6baa3fc2ffd0cb(build key)- Signed source
docs/website/content/generated/artifacts/adrs/adr-002-microsite-ia.md- Signed
- 2026-09-30T20:48:46Z
- Content digest
sha256:426816b7…48d38e22
Endorsed by the human key for seal recognition (ADR-003).
Raw attestation JSON
{
"payload": {
"innsigle": "1",
"type": "https://innsigle.dev/claim/colophon/v1",
"issued_at": "2026-09-30T20:48:46Z",
"issuer": {
"id": "innsigle",
"name": "Innsigle",
"key_id": "ed25519:050bf4d0361a96aa3b6baa3fc2ffd0cb",
"key_url": "https://documentdrivendx.github.io/innsigle/.well-known/innsigle/keys.json"
},
"subjects": [
{
"uri": "https://documentdrivendx.github.io/innsigle/reference/artifacts/adrs/adr-002-microsite-ia/",
"digest": {
"alg": "sha256",
"value": "426816b7bb4bd3935c47d40db149b650fd313b6e7d9d8e6ebf32c26148d38e22"
}
}
],
"colophon": {
"schema_version": "1",
"composition": "model-primary",
"ingredients": [
{
"kind": "model",
"name": "Claude",
"role": "draft"
},
{
"kind": "tool",
"name": "sloptimizer",
"role": "rewrite"
},
{
"kind": "human",
"name": "operator",
"role": "structure-edit"
}
],
"notes": null
}
},
"payload_encoding": "json",
"signatures": [
{
"key_id": "ed25519:050bf4d0361a96aa3b6baa3fc2ffd0cb",
"alg": "ed25519",
"sig": "k7mp7Vg9WQNxufqFxEZJN4b9AuFWpihYT2LSTe4uJjZRDfT6sQw36ZNZCXwZ1inzmSr0egXOSwx3Mrd7CHc7Ag",
"signed_at": "2026-09-30T20:48:46Z"
}
]
}