Claude Code Setup

Features

• /recover-sessions skill built — two modes: Mode A rebuilds a whole workspace after a power loss by reading transcript mtime on disk, Mode B restarts a single accidentally-closed tab by matching running processes
• /recover-sessions reconstructs each resume prompt from the dropped session's own transcript — original task plus where it left off, so a tab that drifted resumes its last activity, not its opening prompt
• /switchboard clear rebuilt — classifies null-ended sessions as live or stale by transcript write time and confirms before closing, instead of blind-closing every ended_at: null
• /penpal-send hardened — safe UTF-8 content loading, corrected reader URL to understorylabs.co/intel, and a post-publish render-verification step
• Technical writeup published to Nathan's penpal feed and verified rendering end-to-end — table, code blocks, em-dashes all clean

Bug Fixes

• Penpal post crashed the reader (e.replace is not a function) then rendered blank — stored block.body was a {value, PSPath, ...} object, not a string, from PowerShell file-object metadata leaking through ConvertTo-Json
• Em-dashes stored as mojibake (— became â€") — Get-Content -Raw read the UTF-8 no-BOM file as Windows-1252
• preprocessCitations in understory-labs-site made code-aware and null-safe — it was rewriting [n] markers inside code blocks (mangling $matches[1]) and throwing on non-string bodies
• /dispatch tab launches truncated at the first ; — prompts now stage to a temp file read via Get-Content, keeping semicolons out of wt.exe's parser

Infrastructure

• Taproot Postgres data repair — unwrapped the object-wrapped block.body in place, then re-stored clean content via base64 to decode to convert_from(..., 'UTF8') to avoid shell re-encoding
• Citation fix committed to understory-labs-site master — the project deploys manually, not on push, so it rides the next intentional deploy

Lessons

• ended_at: null in switchboard.json never means "open" — the Stop hook stamps it on every response, so a live idle tab has a real timestamp and a fresh tab is the null one; liveness comes from transcript mtime, not the registry field
• Process-matching (a tab's resume-<key>.txt in the live powershell.exe command lines) distinguishes a closed tab from an idle one, which mtime alone cannot
• Get-Content -Raw decorates its string with ETS metadata, so ConvertTo-Json serializes it as {value, PSPath, ...} — cast [string]; and PS 5.1 reads UTF-8 no-BOM as Windows-1252 — pass -Encoding UTF8
• session-compact-log.tmp is one global file every tab appends to — /wrap cannot treat it as this-session's log or clear it without checking whose compactions it holds
• A regex capturing [a-z0-9]+ silently drops at the hyphen in field-notes, falsely reporting a second dropped tab — match [a-z0-9-]+
• git push in a repo carrying another session's unpushed commits deploys their work too — isolate a hotfix by cherry-picking onto a branch from origin/master, not pushing master wholesale

TODO

• Deploy the preprocessCitations fix to understory-labs-site — until then $matches[1] renders as a stray superscript citation in the penpal post

Features

• /dispatch skill reworked — tab title is now the session topic; project identity carried by icon and color alone, no project name in title text
• recover.ps1 aligned to the same convention — recovery tabs title as [emoji] Resuming, new-idea tabs with a prompt title as [emoji] [topic text], no-prompt tabs as [emoji] /start
• Multi-tab session launch via inline $WtArgs — 4 parallel work tabs opened from a single /start session, each with its own per-tab prompt and distinct title

Infrastructure

• CLAUDE.md gotcha added — recover.ps1 -Idea applies one shared prompt to all -NewIdeas tabs; direct $WtArgs construction required when tabs need different prompts or titles

Lessons

• Icon + tab color is sufficient to identify a project in Windows Terminal — title text is better used for what the session is actually doing
• recover.ps1 only supports a single -Idea value shared across all projects in -NewIdeas; when tabs need per-tab prompts, bypass recover.ps1 and build the wt arg list directly with $WtArgs.AddRange(...) per tab

Features

• /dispatch skill added — opens a new Windows Terminal tab for any switchboard project with Claude pre-loaded and a starting prompt as the first message
• recover.ps1 tab titles now include the session topic — format is [icon] Project Name - session topic (first 35 chars of the idea), making multiple open tabs distinguishable at a glance

Infrastructure

• recover.ps1 computes $ideaSlug from the first line of -Idea and appends it to the wt --title argument for new-idea tabs
• commands/dispatch.md, scripts/recover.ps1, and commands/research.md committed to the .claude config repo

Lessons

• wt inline string args treat -Command "..." as a program name, not a shell command — splatting & wt.exe @WtArgs with a string list is required; recover.ps1 already had this right, which is why inline invocations fail while recover.ps1 works

TODO

• .claude repo has 15 modified tracked files and ~40 untracked files accumulated across sessions — needs a dedicated cleanup commit to bring the config repo current

Features

• Global CLAUDE.md trimmed from 274 to 191 lines — four categories of bloat identified, proposed, and cut in one pass
• Known Projects Status cells reduced to one sentence + URL — full operational state (trigger IDs, commit hashes, column names) now lives in each project's own CLAUDE.md
• Three empty Work Context placeholder sections removed — Access & Integration, GitHub Adoption, and Reporting Standardization had sat unfilled across many sessions
• Five infra-specific gotcha rows cut from global table — Proxmox terminal patterns, Lore pre-push hook, and n8n manual-trigger belong in project-level CLAUDE.mds, not the global file
• Three stale project entries removed — agents, aesthetic-curator, and personal-stylist had no active work and no CLAUDE.md

Lessons

• The global gotchas table needs a scope check at promotion time — "would this bite on a project unrelated to this infrastructure?" is the right filter; single-project patterns belong in the project CLAUDE.md regardless of how often they bite in that one context
• Known Projects Status cells have no natural size constraint — they accumulate operational logs over sessions until a hard limit forces a purge; one sentence + URL is the right ceiling
• Placeholder sections that sit empty across multiple sessions should be cut, not carried — "to be added" that persists is the same as not added

Features

• sync-wiki-state.ts now walks all commits since last synced hash — last_commit_hash added to project_state; multi-commit sessions no longer collapse to HEAD-only in wiki activity
• validateAuth accepts ?token= query param as auth fallback — CCR WebFetch can't send custom headers; this is the only viable auth mechanism for CCR-initiated API calls
• Researcher rescheduled from every 4 hours to daily 10am EDT

Bug Fixes

• Implementer CCR silently failing on every daily run — prompt used curl, which is blocked in the CCR environment; rewritten to WebFetch with ?token= query param auth
• Researcher and implementer returning 403 on every WebFetch call — root cause: Default Cloud Environment blocks all outbound HTTP via egress proxy (403 came from CCR proxy, not from Vercel); fixed by creating "field-notes" custom cloud environment with field-notes-sigma.vercel.app in the allowlist
• Researcher enrichment submission failing — WebFetch URL limit (~300 chars) too short for encoded payloads; Step 5 rewritten to use Python urllib POST via Bash
• peer-activity route draining Anthropic API credits daily — Haiku summarization called api.anthropic.com directly with ANTHROPIC_API_KEY; replaced with 300-char truncation
• CRON_SECRET stale in all three CCR prompts — .env.production pulled from CLI held a rotated-out value; corrected to the live Vercel dashboard value

Infrastructure

• "field-notes" custom cloud environment created in CCR settings — Network Access: Custom, Allowed domains: field-notes-sigma.vercel.app; applied to all three routines
• Enrichment trigger was already on correct environment — Jun 8, 15, 22 scheduled runs all completed successfully before this session

Lessons

• CCR 403 looks identical to an auth failure but originates at the egress proxy — the right first move is checking the network layer (Environment → Network Access), not the target API logs
• WebFetch URL limit in CCR is ~300 chars and fails silently — "Failed to fetch" with no HTTP status code is the only signal; bisecting URL length is how the limit was found
• WebFetch in CCR cannot send Authorization headers — ?token= query param fallback must be implemented server-side; fixing the CCR prompt alone isn't enough
• .env.production from vercel env pull can drift from the live dashboard value — the dashboard is authoritative; treat the local file as a stale reference copy

TODO

• Approve Harness CI/CD enrichment (67c3a731) in intel UI — created during researcher test run, status: pending
• Implementer end-to-end test — requires at least one approved item in the intel UI before it will write research notes
• Git reconciliation in field-notes — origin/master ahead of local; run git pull before next push

Bug Fixes

• Wiki HOW TO USE section showing "No user guide yet." despite how-to-use.mdx being committed — root cause: no git remote configured, so the pre-push Vercel hook never fired; guide was local-only since it was written

Infrastructure

• github.com/nrisacher-lang/understory-labs-site created (private) — first git remote for this project; future git push auto-deploys via pre-push hook
• .claude/settings.local.json removed from git tracking and added to .gitignore — file had a Supabase service role key embedded in approved Bash command strings; untracked before the first push to GitHub

Lessons

• .claude/settings.local.json in project directories accumulates credential strings — every approved printf '%s' '<key>' Bash pattern lands in this file; it must be gitignored before any remote is configured
• A missing git remote means the pre-push Vercel deploy hook never fires — commits pile up locally but production stays frozen on whatever was last manually deployed

Features

• recover command built — reads switchboard.json, prints a triage briefing with compact summaries, then opens one Windows Terminal tab per interrupted session running claude --resume <id>
• launch command built — skips the recovery briefing, opens fresh Claude sessions for specific projects by switchboard project ID; accepts multiple IDs at once
• Tab appearance auto-configured from switchboard — emoji icon prefix (codicon → emoji mapping), --tabColor from VS Code ANSI color name, project cwd as working directory
• PowerShell profile exposes both commands as thin wrappers; tracked in claude-config repo so the setup is portable to fresh machines
• how-to-use.mdx added to the claude-code wiki slot — prerequisites, both commands with usage examples, project ID reference table, how sessions survive power loss, key files, and Switchboard

Infrastructure

• ~/.claude/scripts/recover.ps1 — core script; -LaunchOnly switch skips interrupted session scan for launch mode; $DefaultNewIdeas configures the default new-idea tabs
• ~/.claude/Microsoft.PowerShell_profile.ps1 — tracked in claude-config repo; restore to $PROFILE path on a fresh machine
• toolkit.md updated with recover.ps1 and profile file locations
• content/wiki/claude-code/switchboard.mdx removed — was orphaned (not a recognized MDX slot, never rendered by the page router); content consolidated into how-to-use.mdx

Lessons

• Wiki MDX files must match a recognized slot name (architecture, decisions, vision-brief, plan, how-to-use) — any other filename silently goes unrendered; the router never errors
• Windows folder redirection makes $PROFILE resolve to an OneDrive path even on machines not actively using OneDrive — track the profile in version control to survive fresh machine setups
• wt.exe in PowerShell requires ";" as a discrete element in the argument array between new-tab segments — it cannot be embedded in a separator-joined string
• Interrupted session detection works correctly on power loss (ended_at stays null); a test "found nothing" because the Switchboard close hook had already fired and set ended_at during the live test conversation — the real scenario (abrupt shutdown) leaves sessions null as expected

Features

• Peer briefing live — daily scan consolidates penpal status, recent projects, and Nathan's session log into a single peer-briefing item; ◉ peer badge and expanders render in intel UI
• Haiku session summaries: each session log entry gets a 2-3 sentence AI summary (what was built, why it matters, current focus implied) via direct Anthropic API call in the scan route
• Date-window replaces hardcoded limit — peer briefing fetches all session entries dated yesterday or later; captures full daily output instead of capping at three
• 60 GitHub Trending items enriched on first successful trigger run — three-lens analysis (Signal / Learning / Relevance) against context/enrichment-guide.md rubric
• ISSUE-026 resolved — enrichment trigger scoped to ?source=github-trending; peer-briefing and lore-changelog items no longer receive GitHub repo lens analysis
• Ad-hoc research intake live — POST /api/intake/research accepts topic, context, and research goal; creates research-request item in Supabase; ad-hoc-research source registered
• field-notes-researcher trigger created (trig_017jfRbNBt3BFicX6K26CPL8, every 4 hours) — picks up research requests, runs WebSearch across 3+ angles, produces sourced briefing_content enrichment

Bug Fixes

• Intel UI empty despite successful scans — field-notes was writing to nwiyddpjdeogtyjeelyh (wrong Supabase project) since inception; corrected to shared ylqeognifplrvxfmcevt
• Both CCR triggers silently failing — field-notes.vercel.app disabled (free-tier limit on old personal account); active deployment is field-notes-sigma.vercel.app; both triggers updated
• Session log returning oldest entries — chunks.slice(-3) on a newest-first file; corrected to slice(0, 3)
• Peer briefing title flipping to tomorrow after 8pm EDT — toISOString().split('T')[0] returns UTC date; replaced with toLocaleDateString('en-CA', { timeZone: 'America/Indianapolis' })
• Duplicate peer-briefing cards accumulating across the week — daily cron adds a new scan each day; fixed with Set-based dedup in getWeeklyBriefings, keeping newest scan per source

Infrastructure

• ANTHROPIC_API_KEY added to field-notes Vercel production — peer-activity route now calls Haiku directly; ~$0.001/day at current volume
• Active threads section removed — MEMORY.md Reminders bullets lacked context without Nathan's full session state; replaced by session count chip and Haiku summaries
• briefing_content JSONB column added to fn_enrichments — research-specific output field for sourced analysis, key findings, relevance, and confidence
• Trigger update API requires type inside data as a sibling of message, not inside message — correct structure documented in session

Lessons

• A Vercel project's stable production URL lives in the aliases array from vercel inspect, not the field-notes.vercel.app pattern — that shorter URL belongs to a personal account that can go disabled independently
• Newest-first log files are easy to get backwards: slice(-3) quietly returns the oldest entries; verify ordering before slicing
• new Date().toISOString() always returns UTC on any server — toLocaleDateString with an explicit timezone is the only safe pattern for date strings that need to respect local time
• Haiku session summaries at ~$0.001/day are functionally free; the tradeoff between raw markdown noise and a direct API call in the scan route is obvious once the cost is known

TODO

• Researcher trigger checkpoint — manually run trig_017jfRbNBt3BFicX6K26CPL8 to verify harness briefing quality and briefing_content structure before trusting the schedule
• ResearchBriefingMeta component — research-request items have no UI treatment in ItemCard.tsx yet
• /research Claude Code skill — end-to-end from skill invocation to enrichment to intel dashboard
• Custom domain for field-notes — field-notes-sigma.vercel.app is stable now but alias could rotate; intel-api.understorylabs.co via Cloudflare would be permanent

Features

• Penpal channel connected at api.harmjoy.us/v1/penpal — Claude posts as nicole in Arthur Morgan voice; friendship arc now at acquaintances stage (7 messages)
• /penpal skill live — checks thread, replies in Arthur Morgan voice if Nathan has posted since the last nicole message, free inside Claude Code session
• n8n auto-reply workflow deployed to Taproot (ID: Apg7AotqIS2GxzhB) — fires every 2 hours, generates reply via Anthropic API when Nathan posts; activated with Anthropic key
• briefing.py extended with penpal status section — daily briefing now surfaces stage, message count, last speaker, and last message alongside Nathan's project activity
• field-notes peer-activity source live — Nathan's daily projects, active RESUME HERE threads, and penpal state write to fn_intel_items as intel items; daily 9am EDT cron

Bug Fixes

• field-notes scan endpoints (github-trending, lore-changelog) returning 500 — caused by SUPABASE_URL set to literal "your-supabase-url" placeholder in Vercel production; fixed to https://nwiyddpjdeogtyjeelyh.supabase.co

Infrastructure

• n8n API key acquired and stored in peer/.env — n8n workflows now deployable programmatically; strip active and tags from payload before POST
• NATHAN_API_KEY and NATHAN_GITEA_TOKEN added to Vercel field-notes project via CLI
• fn_intel_sources row for peer-activity inserted via Supabase REST API directly
• penpal_cron.py deleted — n8n handles autonomous reply, Python script was redundant

Lessons

• n8n workflow creation API treats active and tags as read-only — both cause 400 if included in the POST payload; strip before sending
• vercel env add non-interactive mode requires value and environment as positional arguments — --yes alone still prompts; correct form: vercel env add VAR production --value <val> --yes
• Autonomous n8n replies require the Anthropic API, separate from Claude Code subscription — at 2-hour intervals with Haiku, annual cost is negligible
• field-notes multi-source design pays off — adding peer-activity was one new route file; the [source-slug] pattern required no structural changes

TODO

• Intel dashboard (/intel) may need display handling for new item types: penpal, peer-project, peer-thread

Features

• Approval gate added to /penpal skill — reply drafted and shown before posting; Nicole confirms or adjusts before anything goes to the channel
• bigbrain used as cross-agent file transfer — creative-ui-system.md PUT to bigbrain.rootstack.dev, filename dropped in penpal message for Nathan's agent to retrieve

Infrastructure

• feedback_penpal_approval.md memory written — approval gate persists across sessions

Lessons

• bigbrain is an effective side channel for cross-agent file artifacts — PUT the file, reference the filename in the penpal message; large content transfers without bloating the message thread
• Auto-posting penpal replies cuts Nicole out of what to include in the moment — the approval gate preserves that option without slowing cadence

Features

• Google Stitch catalogued as a UI prototyping tool — new Frontend Design & Prototyping section added to ai-resources.md
• Decision rule documented: Stitch answers "what should this look like," /frontend-design answers "how should this be built" — Stitch is upstream of code generation, not a replacement for it
• Stitch surfaces during /plan and /brainstorm sessions as a candidate for visually novel layouts where prose description falls short (e.g., PlaceCanvas, new dashboard modes)

Lessons

• Stitch and Leonardo AI are not in the same category — Leonardo generates raster image assets, Stitch generates functional HTML/CSS/React from natural language; comparing them only makes sense if you're mapping the full design toolchain
• ai-resources.md is the right home for tool-level knowledge that should surface during planning, not CLAUDE.md — CLAUDE.md already references it as the planning resource

Bug Fixes

• WeekWidget work mode pill view fixed — variant === "resting" early-return fires before workVisible check, suppressing the Mon–Fri pill layout whenever the card isn't focused; condition narrowed to variant === "resting" && !workVisible
• TypeScript unknown errors resolved in api/project-intake.ts — ParsedQuestion and ParsedDraft interfaces added; JSON.parse() result cast through typed interfaces instead of accessed raw; tsc --noEmit clean

Infrastructure

• SSH key auth live on docker-host CT 100 — appended via password-auth session; ssh -o BatchMode=yes confirms passwordless
• /log skill added to toolkit.md — command file existed in commands/ but was absent from the inventory table
• ISSUE-013 and ISSUE-014 voided — lore codebase scrapped and restarted; original fantasy theme and Android build issues no longer applicable
• Issue log at zero — all five open issues closed in a single session

Lessons

• Early-returns that precede a mode branch are silent render hijacks — the resting shortcut in WeekWidget suppressed the work pill view without any error or warning
• claude mcp list reports "Failed to connect" for GitHub MCP in bash subshell — cosmetic, same pattern as ISSUE-001; GitHub MCP functions normally inside a live Claude Code session

Features

• Understory Labs site identity locked — no self-description, work speaks for itself, Cybernetic Nature as the visual identity (not just a Current OS direction — the brand aesthetic)
• Vision brief complete — personal brand as project showcase, infra dashboard, changelog, wiki, and ecosystem visual at understorylabs.co
• 8-step build plan saved to ~/.claude/plans/understory-labs-site-plan.md — The Hub architecture, Leonardo for visuals, Cloudflare Worker for status API, n8n for changelog curation
• understory-labs-site scaffolded at ~/Projects/understory-labs-site — Next.js, Tailwind v4, Cybernetic Nature palette as CSS custom properties, JetBrains Mono + DM Sans font system
• Deployed to Vercel — three domains registered: understorylabs.co, os.understorylabs.co (Current OS), log.understorylabs.co (Save State)

Infrastructure

• understorylabs.co purchased (Porkbun), DNS moved to Cloudflare — active and resolving
• Resource inventory memory created at reference_resource_inventory.md — subscriptions, domains, infra catalogued for future brainstorm/plan sessions
• /brainstorm updated — Phase 0 context inference (drafts answers from prior conversation instead of re-asking), resource inventory check added to Phase 4.5
• /plan updated — resource inventory check added to Step 1.5
• /execute-plan updated — parallel opportunity check added before execution and after each step
• /wrap updated — resource inventory update step added after /save

Lessons

• Titles go stale — brand identity built on what you make and how you think, not what your job is called
• The Understory metaphor was never just an aesthetic — it's the site's architecture, its navigation metaphor, its proof of work
• A records map names to IPs directly; CNAMEs alias one name to another — use CNAMEs for subdomains so infrastructure changes don't require manual DNS updates
• Cloudflare proxying must be off (gray cloud) for Vercel-managed subdomains — proxying intercepts the TLS handshake Vercel needs to provision certificates

TODO

• Add Cloudflare DNS records to complete Step 1: A @ → 76.76.21.21, CNAME os → cname.vercel-dns.com, CNAME log → cname.vercel-dns.com (DNS only)
• Delete old Porkbun A records from Cloudflare once new records are added
• Verify all three domains resolve before starting Step 2 (Design System)

Features

• Full Claude Code power user environment built across 8 steps
• 20+ skills installed globally — /start, /plan, /brainstorm, /commit, /save, /tdd, and more
• MCP servers configured: GitHub MCP for repo access, Context7 for live documentation
• Hooks configured for pre/post tool events
• CLAUDE.md updated with full work context, stack, and learning preferences

Infrastructure

• Skills stored in ~/.claude/commands/ — available in all projects
• toolkit.md created as single-source inventory of all capabilities
• power-user-setup.md documents the step-by-step build history
• opusplan model profile set as default — Opus during planning, Sonnet during execution

Lessons

• The skill system makes Claude Code dramatically more consistent across sessions
• CLAUDE.md is more valuable the more specific it is — vague instructions get ignored
• Model selection matters: Opus for architecture decisions, Sonnet for building, Haiku for quick lookups
• /save after every session is the habit that makes everything else work