Innsigle Reference ADR-002: Microsite information architecture and content pipeline

Generated reference: edit sources under docs/helix/, then npm run site:build.

Generated from HELIX docs. Source: docs/helix/02-design/adrs/ADR-002-microsite-ia.md. Edit the source, not this file or site/ 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

DateStatusDecidersRelatedConfidence
2026-07-23AcceptedOperatorproduct-microsite-ia concern; PRD brand site FRsHigh

Context

AspectDescription
ProblemPublic site mixed hand HTML with specs; HELIX concern requires reader-mode IA and generated reference from artifact sources
RequirementsAuto-publish walkthroughs/specs/design docs/glossary from docs/; keep carefully curated copy outside the HELIX source tree (docs/helix/)
Driversproduct-microsite-ia; DESIGN.md voice; dual UC evaluate/start/operate paths

Decision

We will use a two-layer content model:

  1. Curated product copy under docs/website/content/curated/ (outside

docs/helix/). Hand-authored Why / Use / Non-goals pages for evaluate and start reader modes.

  1. Generated reference under docs/website/content/generated/, rebuilt

deterministically from docs/helix/ (and glossary sources) by scripts/publish-artifacts.mjs.

  1. Build HTML into site/ via scripts/build-site.mjs using DESIGN.md tokens

and IA from docs/website/ia.yml.

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

OptionProsConsEvaluation
Hand-only static HTML in site/SimpleSpecs drift; violates microsite concernRejected
Full Hugo/Hextra like HELIXMatureHeavy for v0; dependency burdenDeferred
Curated MD + generate artifacts → static buildMatches concern; light depsCustom builderSelected

Consequences

TypeImpact
PositiveSpecs stay in docs/helix/; site always regenerable; IA named by reader mode
NegativeMust run publish+build before deploy
NeutralSample and marks still synced as static assets

Risks

RiskProbImpactMitigation
Hand-edit generated HTMLMMWipe site/ content pages on build; README warnings
Nav hides core leavesLHia.yml core_leaves + concern quality gates

Validation

Success MetricReview Trigger
npm run site:build produces Why/Use/Reference + artifact pagesIA change
Generated artifact index groups by activityHELIX tree reorg

Supersession

  • Supersedes: None
  • Superseded by: None

Concern Impact

  • Satisfies product-microsite-ia ADR requirement (IA model + content pipeline).
  • Updates concerns.md practice 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"
    }
  ]
}