# Spec Sheet — Archive Capture

**What you are building:** A skill that records what the current chat covered, gathers every file the chat produced (including the scripts that generated them), and pushes the bundle to an inbox folder in a private "transport" git repository so it can be filed later on another machine.

> Bracketed [PLACEHOLDERS] are yours to fill in for your own setup. Any credential is redacted: supply your own via a secret store or an environment variable, and never paste a token into a skill file, a summary, or any shipped artifact.

## 1. Purpose

Chat containers are ephemeral. When a session ends, its working files and the scripts that built them are lost, and only manually downloaded outputs survive. This skill makes preserving a session a single instruction. It writes a descriptive record of the conversation, copies the artifacts plus their source recipes into a dated bundle, and pushes that bundle to a private repo that couriers it to your main machine for filing. It is deliberately descriptive — it records *what happened*, it does not extract or curate *settled conclusions*. (If you also want a settled-thinking extractor, build that as a separate skill; keep the two from imitating each other.)

## 2. Activation

- **name:** `archive-capture` (or `[your-capture-name]`).
- **description:** must make the model auto-trigger when the user asks to save or capture the current chat. Include the literal trigger phrases you want — e.g. "archive this chat", "run archive capture", "capture to the archive" — and state what it does (writes a structured summary, gathers every produced file including generating scripts, pushes to the inbox of the transport repo). If you also run a separate settled-thinking capture, end the description by distinguishing the two so the model picks the right one.

## 3. Inputs and preconditions

- The current conversation (read by the model to write the summary).
- Every file the chat produced, found in the container's outputs directory (e.g. `[/mnt/user-data/outputs]`) and the working directory.
- The scripts/generators that produced those files, wherever they live in the container.
- Precondition: a writable scratch path in the container (e.g. `[/home/claude]`) and git available.

## 4. Outputs and side effects

- A bundle directory named `YYYY-MM-DD--<short-topic-slug>` containing:
  - `summary.md` (structured record, format below).
  - Copies of every produced artifact and its source recipe.
- Side effect: a commit pushed to `[DEST_INBOX]/` in the transport repo under your chosen commit identity.

## 5. Environment and dependencies

- **Transport repo:** a private git repository acting as a courier between ephemeral chat containers and your local machine. Generalize as `https://github.com/<owner>/<repo>.git`.
- **Destination folder:** an inbox path inside that repo, e.g. `[archive-inbox]/`, where bundles land for later filing.
- **Credential:** push access via a token. Do NOT embed a token in the remote URL in a shared or committed skill. Prefer a secret store / environment variable that the container injects at run time. Treat the token as `[PERSONAL_ACCESS_TOKEN]`.
- **Commit identity:** a name and email, e.g. `[YOUR NAME] <[your-noreply-email]>`.
- **Downstream filer (optional):** a separate skill or process that pulls the inbox and files bundles into your archive taxonomy.

## 6. Procedure

1. **Name the bundle:** `YYYY-MM-DD--<three-to-six-word-slug-of-the-topic>`.
2. **Write `summary.md`** with frontmatter `date`, `surface` (web | mobile | desktop), `title`, `provenance: chat-capture`, then these sections in order:
   - **What this chat covered** — 3 to 8 sentences, descriptive, past tense.
   - **What was produced** — one line per artifact describing what it is.
   - **Decisions and positions** — anything that sounded settled. Open this section with a literal marker line that flags it as record-only and not authoritative (e.g. `FLAG FOR CURATED CAPTURE — record only, not authority`). This is the seam to any separate curated-thinking pipeline.
   - **Open threads.**
3. **Gather artifacts:** copy everything the chat produced from the outputs directory and the working directory into the bundle. Always include source recipes (scripts, generators) alongside rendered outputs. If an earlier file is gone because the container reset, say so plainly and regenerate it from its recipe where possible. Never silently skip a missing artifact.
4. **Ship** (substitute `<bundle>`; keep the credential out of the working tree):
   - `git clone --depth 1 "$REPO" [scratch]/transport`
   - `mkdir -p "[scratch]/transport/[DEST_INBOX]/<bundle>"`
   - `cp -r <bundle contents> "[scratch]/transport/[DEST_INBOX]/<bundle>/"`
   - `cd [scratch]/transport`
   - set `user.email` and `user.name` to your commit identity
   - `git add -A`
   - `git commit -m "capture: <bundle>"`
   - `git push`
   - If the push is rejected: `git pull --rebase`, then push once more.
5. **Confirm** with the bundle name, the file list, and the actual push output quoted verbatim. Never report success without quoting the real push output.

## 7. Edge cases and failure handling

- **Missing artifact (container reset):** state plainly that the file is gone and why; regenerate from its recipe if possible; never drop it silently.
- **Push rejected (remote ahead):** `git pull --rebase` then push once more.
- **Push fails twice:** present the bundle as downloadable files and state explicitly that transport failed, so the user still gets the content.
- **Nothing produced:** still write `summary.md`; a record of the conversation alone is valid.

## 8. Guardrails / hard rules

- This is a **descriptive** record. Do not write to or imitate any separate settled-thinking capture format.
- **Never** put the token in `summary.md` or any shipped file. The credential exists only to authenticate the push.
- Always bundle source recipes next to rendered outputs.
- Never report success without quoting the actual push output.
- If the push fails twice, fall back to downloadable files and say transport failed.

## 9. Acceptance criteria

- Triggering on the phrases in the description starts the capture.
- The bundle is named `YYYY-MM-DD--<slug>` and contains `summary.md` plus copies of every produced artifact and its generating script.
- `summary.md` has the required frontmatter and the four sections in order, with the record-only marker opening the decisions section.
- A commit named `capture: <bundle>` appears in `[DEST_INBOX]/` of the transport repo, authored by the configured identity.
- The final message quotes the real push output verbatim.
- No token appears anywhere in the bundle.
- A reset/missing artifact produces an explicit note, never a silent omission.

## 10. Adapt to your setup

- Swap the transport repo, inbox folder, and commit identity for yours.
- Replace any embedded-token remote with a secret-store or env-var credential; never commit a token.
- Adjust the outputs directory and scratch paths to your container's layout.
- Choose your own `surface` values if web/mobile/desktop don't fit.
- If you have no curated-thinking pipeline, keep the decisions section but drop the cross-reference; if you do, point the marker line at it.

---

```markdown
---
name: archive-capture
description: >-
  Capture this chat into the personal archive. Use when the user says
  "archive this chat", "run archive capture", or "capture to the archive".
  Writes a structured summary of the conversation, gathers every file the
  chat produced (including the scripts that generated them), and pushes the
  bundle to [DEST_INBOX]/ in the private transport repository. Records what
  happened; does not extract settled positions.
---

# Archive capture

## Configuration
REPO   = https://github.com/<owner>/<repo>.git   # auth via [PERSONAL_ACCESS_TOKEN] from a secret store — never inline
DEST   = [DEST_INBOX]/
COMMIT IDENTITY = [YOUR NAME] <[your-noreply-email]>

## Procedure
1. Name the bundle: YYYY-MM-DD--<short-topic-slug>.
2. Write summary.md (frontmatter: date, surface, title, provenance: chat-capture;
   sections: What this chat covered / What was produced / Decisions and positions
   [open with the record-only marker line] / Open threads).
3. Gather artifacts from outputs + working dir; include source recipes; never skip
   a missing file silently.
4. Ship: clone --depth 1, copy bundle into DEST, set identity, add, commit
   "capture: <bundle>", push; on reject pull --rebase then push once more.
5. Confirm with bundle name, file list, and the real push output quoted.

## Hard rules
- Descriptive record only; do not imitate any settled-thinking capture format.
- Never place the token in summary.md or any shipped file.
- If the push fails twice, present downloadable files and say transport failed.
```