# ADR-0002: Kit is fully self-contained on export; no external references survive

- **Date:** 2026-04-28
- **Status:** accepted
- **Reversibility:** high (the constraint can be relaxed in V1.x by introducing a network resolver, but loosening it is a breaking change for offline deployments)
- **Deciders:** practitioner@example.com (operator)
- **Scope:** kit (V1 export contract)

## Context

The kit will be packaged as `MarTech-Deployment-Kit-V1-{date}.zip` and dropped into a fresh Cowork environment. The deployed instance has no guaranteed access to the operator's personal-practice library (`AI-Architect/`), to the operator's filesystem, to external internet resources, or to any system outside the Cowork sandbox.

Three real options exist for handling cross-references the kit's documents make to source material:

- **Self-contained:** every reference inside the kit resolves inside the kit. Source material that the kit derives from gets copied or restated into kit-internal artifacts.
- **Reference-external:** kit documents may reference paths in the operator's source library (`AI-Architect/fundamentals.md`, the Cowork skills folder, etc.); the deployed instance fetches them as needed.
- **Hybrid:** kit ships self-contained for core methodology but externalizes optional or rarely-touched references.

Operator constraint locked 2026-04-28: "this kit will be fully exported so everything MUST be self contained."

## Decision

The kit is fully self-contained. Every cross-reference in any kit document resolves to an artifact inside the kit's directory tree. Source material that the kit derives from gets copied or restated into kit-internal form, with the source attribution recorded but the dependency severed at export time.

## Options considered

### Option A: Self-contained [CHOSEN]

- **Summary:** Every reference resolves inside the kit. `BOOTSTRAP-BRIEF.md` restates the methodology; skills are mirrored with `MIRRORED FROM` headers but their content travels with the kit; the worked example uses placeholder tokens rather than referencing any external system.
- **Pros:** Works in any environment, including offline; survives operator filesystem changes; works after the operator's personal library is renamed or restructured; the deployed instance never fails because a path went stale.
- **Cons:** Larger zip; updates to source material (e.g., `fundamentals.md` v1.3) require a new kit version, not an automatic refresh; some duplication between kit content and personal-library source.

### Option B: Reference-external

- **Summary:** Kit documents reference operator-personal paths (e.g., `AI-Architect/fundamentals.md`); deployed instance fetches them.
- **Pros:** Kit stays small; updates to source material flow into all deployed instances automatically; no duplication.
- **Cons:** Cowork sandbox cannot reach the operator's filesystem; deployment fails on first reference; security and IP boundary issues if the kit deploys into work systems and references personal paths; brittle to any source-side rename.

### Option C: Hybrid

- **Summary:** Core (BOOTSTRAP-BRIEF, QUESTIONS, templates, worked example) ships self-contained; rarely-touched references (e.g., supplementary reading on the Recursive Engine) externalize.
- **Pros:** Smaller zip than Option A; preserves some auto-update capability for non-core content.
- **Cons:** Same fragility as Option B for any externalized reference; introduces a two-class system (core vs. supplementary) that the deployed instance must reason about; operator must remember which references are which when authoring.

## Rationale

Option B is structurally infeasible for the Cowork target. Option C reintroduces every Option B failure mode for the externalized references and adds cognitive overhead (two-class system). Option A is the only architecture that survives the actual deployment environment.

The tradeoff explicitly accepted: source-material updates require a new kit version, not auto-propagation. Mitigation: the kit's `Last reviewed` frontmatter and the operator's quarterly cadence make staleness visible; v1.x patch releases handle source-side updates.

The duplication between kit-internal restatements and personal-library source is real but acceptable: the kit's restatements are reshaped for fresh-actor consumption, not verbatim copies; the personal library remains the source of truth for the operator's own work; the kit's snapshots are dated and attributed.

## Consequences

### Positive

- Kit deploys cleanly into any environment regardless of host filesystem
- Survives operator-side renames, restructures, and library migrations
- The deployed instance never fails because of a stale external path
- IP boundary is automatically respected: nothing in the deployed instance points at personal-side paths

### Negative

- `BOOTSTRAP-BRIEF.md` duplicates content from `AI-Architect/fundamentals.md` (reshaped, not verbatim)
- The 45 Cowork-mirrored skills are dated copies; updates to the originals do not flow into already-deployed kits
- Kit zip size includes the full skill payload (~50 to 60 MB depending on multi-file skill bulk)
- Multi-file skills (xlsx 54 files, docx 61 files, pptx 59 files, etc.) inflate the export

### Followups

- Chunk F's export logic verifies self-containment: grep the entire kit for any path starting with `~`, `/Users/`, `AI-Architect/`, or any other operator-personal pattern; flag and fix any matches before packaging
- The `architect-kit-mirror` skill (built in Chunk D) encodes the `MIRRORED FROM` header convention so source attribution survives without making the dependency live
- Future V1.x releases follow `MarTech-Deployment-Kit-V1.{minor}-{date}.zip` naming so deployed instances can detect and prompt for upgrades
