docs(decisions): record ADR-100 desktop capture product; corpus setup guidance intent

rac/decisions/adr-100-desktop-capture-product.md

@@ -0,0 +1,106 @@
+---
+schema_version: 1
+id: RAC-KWRSFV26HZVK
+type: decision
+---
+# ADR-100: Start the Desktop Capture Product — Cross-Platform Tauri Overlay
+
+## Status
+
+Proposed
+
+## Category
+
+Product
+
+## Context
+
+Capture-at-the-moment is the corpus's recorded absent capability
+(`growth-essay-mapping`, Row 6), and the capture architecture is already
+settled: under the two-gate write model (ADR-077) an author answers an
+interview and confirms fidelity — validation runs mechanically inside the
+loop and ratification is an independent pull-request merge — so authoring
+never requires writing Markdown or iterating against a validator. What
+remained undecided was the host surface that reaches the intended audience:
+non-technical knowledge owners, people who will not author through MCP
+servers, coding-agent harnesses, or agents in Slack.
+
+The `lore-overlay` roadmap records a desktop overlay as future intent,
+explicitly gated on "the decision to start a desktop product", and a staging
+spike (rac-core PR #202) validated the two-gate capture core behind trait
+seams. The spike also exposed the real adoption barrier for this audience:
+not the capture UX but the setup — a bring-your-own model gateway and a
+GitHub App are not things a non-technical author will configure.
+
+## Decision
+
+Start the desktop capture product. Specifically:
+
+- **The gate is ratified.** The desktop host is a committed product
+  direction, not exploratory intent. Scheduling remains with its roadmap and
+  execution epic; it must not displace already-scheduled engine work.
+- **Tauri v2, cross-platform from the outset.** The product targets
+  availability across setups, not macOS-first-then-Windows: macOS and
+  Windows are both first-class targets of the initial release cycle. Linux
+  stays deferred (portal/compositor unevenness, per the roadmap's
+  non-goals).
+- **Admin-provisioned deployment.** An administrator configures the model
+  gateway, the GitHub App identity, and the target repository once
+  (composing with the ADR-088 profile-scaffold pattern); the author-facing
+  surface is only hotkey → interview → "is this what you decided?".
+- **Own repository, engine untouched.** A separate product repository
+  slugged `rac-overlay` per ADR-092's `rac-*` naming, with the Lore brand
+  carried at the organisation/marketplace level; the product name
+  ("overlay") remains a working title. The app is a thin client over the
+  `rac` contract (ADR-063); no AI enters the engine (ADR-002).
+- **The two-gate model is non-negotiable.** The app's GitHub identity
+  proposes draft pull requests only and can never approve or merge
+  (ADR-065, ADR-077).
+
+## Consequences
+
+- Lore gains a capture surface for the audience the skill and MCP hosts
+  cannot reach, and a second installable host that proves the
+  skill-is-brain / host-is-interface model. Whether it works is measurable:
+  the artifact-completeness benchmark's residual gives a before/after
+  signal for corpus completeness.
+- Cross-platform from day one costs more than the previously drafted
+  macOS-first path: two signing pipelines (Developer ID notarization and
+  Authenticode/SmartScreen reputation) and two OS integration surfaces
+  before the first release, in exchange for not excluding Windows-based
+  authors at launch.
+- Admin-provisioning documentation becomes part of the product's
+  deliverable, not an afterthought — the product's reach depends on a
+  technical administrator's one-time setup being genuinely one-time.
+- A desktop product carries an ongoing support surface (updates, signing
+  renewals, OS changes) that a repo-resident skill does not.
+
+## Alternatives Considered
+
+- **macOS-first, Windows fast-follow** (the roadmap's prior sequencing) —
+  rejected: the product's aim is availability across setups; sequencing by
+  operating system delays exactly the authors it targets.
+- **Slack bot first** — reaches some non-technical users but not the stated
+  audience: people not comfortable with agents in Slack, and organisations
+  where such bots are restricted.
+- **Skill/MCP surfaces only (no product)** — leaves the capture gap open
+  for everyone who is not already in a coding-agent context.
+
+## Related Decisions
+
+- adr-002-ai-optional
+- adr-063-non-python-clients-are-thin
+- adr-065-artifact-content-untrusted
+- adr-068-extension-sdk-and-brand-architecture
+- adr-077-two-gate-capture-write-model
+- adr-088-enterprise-profile-scaffold
+- adr-092-repository-topology
+
+## Related Roadmaps
+
+- lore-overlay
+
+## Related Designs
+
+- lore-capture-overlay
+- lore-capture-surfaces

rac/roadmaps/future/corpus-setup-guidance.md

@@ -0,0 +1,96 @@
+---
+schema_version: 1
+id: RAC-KWRSFWSF7R4T
+type: roadmap
+---
+# Corpus Setup and Structuring Guidance (Future)
+
+## Status
+
+Planned
+
+Unscheduled — recorded as future intent, not yet on a release. It must not
+displace scheduled engine work; each initiative graduates with its own scope
+and an ADR-093 execution issue when picked up.
+
+## Context
+
+RAC validates artifacts once they exist, but records no opinionated guidance
+on how a team should set up and structure a corpus in the first place.
+Observed at large-organisation scale (a ~2,500-person org): teams set up
+their decision records differently and inconsistently, and default to a
+single "mega-doc" of decisions rather than discrete, individually
+addressable artifacts. A mega-doc defeats the properties the engine is built
+on — per-artifact identity, typed relationships, per-decision lifecycle
+status, and retrieval that can serve one decision to an agent instead of a
+whole file.
+
+The pieces that would fix this exist but are not connected as guidance:
+`rac init` scaffolds configuration (and profiles, ADR-088) but not
+structuring conventions; `rac ingest` can split an existing document into
+discrete artifacts (ADR-006, ingestion over rewrite); the onboarding
+scaffold writes one starter artifact (ADR-044). Nothing tells a team "one
+decision per artifact", how to lay out `rac/`, or how to get from an
+existing mega-doc to a well-formed corpus.
+
+## Outcomes
+
+- A team adopting RAC lands on a consistent, conventional corpus structure
+  without needing a human expert in the loop — the same shape whichever team
+  in the organisation sets it up.
+- The mega-doc anti-pattern has a documented, low-effort exit: an existing
+  decisions document becomes discrete validated artifacts through a
+  recorded path rather than a manual rewrite.
+
+## Initiatives
+
+### Initiative 1 — Opinionated setup and structuring guide
+
+An authored guide (docs-site + README doorway) recording the conventions the
+dogfood corpus already practises: directory layout under `rac/`, granularity
+(one decision or requirement per artifact, and why), naming, when to record
+an ADR versus a requirement versus a design, and how the corpus composes
+with `rac init` / profiles (ADR-088).
+
+### Initiative 2 — Mega-doc split path
+
+A documented recipe for converting a single decisions document into
+discrete artifacts via `rac ingest` (ADR-006): what the tool does, what the
+human reviews, and how the result is promoted through pull-request review
+(ADR-065). Documentation-first; any tooling change needs its own scope.
+
+An advisory structural finding (for example, doctor flagging a single
+artifact that contains many decision-shaped sections) is a candidate
+follow-on, deliberately not committed here — it needs its own decision
+before any gate-adjacent behaviour is added.
+
+## Success Measures
+
+- A new team following the guide alone produces a corpus that passes
+  `rac validate` and `rac relationships --validate` with the conventional
+  layout, without expert help.
+- A real mega-doc has been split into discrete artifacts by following the
+  recorded recipe end to end.
+
+## Assumptions
+
+- ADR-017 and ADR-024 hold: the guidance covers knowledge structure, never
+  work tracking or content storage.
+- `rac ingest` remains the sanctioned conversion path (ADR-006, ADR-072);
+  the recipe documents it rather than adding a parallel mechanism.
+
+## Risks
+
+- Guidance that reads as policy could conflict with how existing corpora
+  are already laid out; the guide records conventions and defaults, not
+  validation rules — anything enforceable needs its own decision first.
+- Over-specifying granularity could push teams into artificial splitting;
+  the guide should state the principle (one addressable decision per
+  artifact) and leave judgement to the author.
+
+## Related Decisions
+
+- adr-006-ingest-over-rewrite
+- adr-044-onboarding-scaffold
+- adr-065-artifact-content-untrusted
+- adr-088-enterprise-profile-scaffold