From b6948fa881af66ba348e69d3ab2c89d2a70ca299 Mon Sep 17 00:00:00 2001
From: Danijel Martinek <danijel@fraqtal.xyz>
Date: Wed, 13 May 2026 09:27:02 +0200
Subject: [PATCH] docs(work): scaffold sandcastle-subscription-auth-v1 epic

---
 docs/work/_state.json                         | 24 +++++++++++++--
 .../01-subscription-first/_story.md           | 21 ++++++++++++++
 .../sandcastle-subscription-auth-v1/_epic.md  | 29 +++++++++++++++++++
 3 files changed, 72 insertions(+), 2 deletions(-)
 create mode 100644 docs/work/sandcastle-subscription-auth-v1/01-subscription-first/_story.md
 create mode 100644 docs/work/sandcastle-subscription-auth-v1/_epic.md

diff --git a/docs/work/_state.json b/docs/work/_state.json
index b2d2dfc..f87ef6c 100644
--- a/docs/work/_state.json
+++ b/docs/work/_state.json
@@ -1,5 +1,5 @@
 {
-  "updated_at": "2026-05-13T07:05:55.913Z",
+  "updated_at": "2026-05-13T07:27:04.538Z",
   "epics": {
     "agent-workflow-docs-v1": {
       "status": "done",
@@ -382,6 +382,20 @@
         }
       }
     },
+    "sandcastle-subscription-auth-v1": {
+      "status": "in-progress",
+      "title": "Sandcastle subscription auth as primary flow",
+      "stories": {
+        "01-subscription-first": {
+          "status": "in-progress",
+          "title": "Subscription-first dispatch — mount ~/.claude, install claude CLI, docs",
+          "ac_total": 8,
+          "ac_completed": 0,
+          "depends_on": [],
+          "blocks": []
+        }
+      }
+    },
     "visual-regression-v1": {
       "status": "done",
       "title": "Visual regression v1 — Playwright screenshot infrastructure",
@@ -435,6 +449,12 @@
       }
     }
   },
-  "ready": [],
+  "ready": [
+    {
+      "epic": "sandcastle-subscription-auth-v1",
+      "story": "01-subscription-first",
+      "title": "Subscription-first dispatch — mount ~/.claude, install claude CLI, docs"
+    }
+  ],
   "blocked": []
 }
diff --git a/docs/work/sandcastle-subscription-auth-v1/01-subscription-first/_story.md b/docs/work/sandcastle-subscription-auth-v1/01-subscription-first/_story.md
new file mode 100644
index 0000000..e09f310
--- /dev/null
+++ b/docs/work/sandcastle-subscription-auth-v1/01-subscription-first/_story.md
@@ -0,0 +1,21 @@
+---
+id: 01-subscription-first
+epic: sandcastle-subscription-auth-v1
+title: Subscription-first dispatch — mount ~/.claude, install claude CLI, docs
+type: technical-story
+status: in-progress
+feature: tooling
+depends-on: []
+blocks: []
+---
+
+## Tasks
+
+- [ ] Story scaffold
+- [ ] Update .sandcastle/Dockerfile to install @anthropic-ai/claude-code CLI
+- [ ] Update scripts/work/dispatch.mjs: resolveClaudeAuth helper + sandbox mount + fallback to API key
+- [ ] Tests for resolveClaudeAuth
+- [ ] Update runbook "Using Sandcastle" section: subscription is primary flow
+- [ ] Update ADR-019: subscription auth as primary, API key as fallback
+- [ ] Update .env.example + .sandcastle/.env.example: reframe ANTHROPIC_API_KEY as fallback
+- [ ] Final verification + closeout
diff --git a/docs/work/sandcastle-subscription-auth-v1/_epic.md b/docs/work/sandcastle-subscription-auth-v1/_epic.md
new file mode 100644
index 0000000..ea6359d
--- /dev/null
+++ b/docs/work/sandcastle-subscription-auth-v1/_epic.md
@@ -0,0 +1,29 @@
+---
+id: sandcastle-subscription-auth-v1
+prd: null
+title: Sandcastle subscription auth as primary flow
+type: epic
+status: in-progress
+features: [tooling, ci]
+created: 2026-05-13
+---
+
+## Goal
+
+Subscription-based Claude Code auth (via host `~/.claude` mount) becomes
+the default for `pnpm work dispatch --execute`. API-key auth remains as a
+fallback. Works for any developer who has run `claude login` on their
+host — zero per-user configuration in the repo.
+
+## Why
+
+The sandcastle community has explicitly rejected native subscription
+support (issue #191, wontfix). But the host's `~/.claude/` directory
+contains the logged-in session; mounting it into the sandbox lets the
+container's Claude Code CLI use that session. This pattern is
+environment-agnostic (each developer has their own `~/.claude`) and
+spends zero per-task agent tokens for Pro/Max subscribers.
+
+## Stories
+
+- [ ] [01 — Subscription-first dispatch + Dockerfile + docs](01-subscription-first/_story.md)