arcane-cli 0.14.0

package/dist/assets/.arcane/governance/hardening-checklist.md

@@ -0,0 +1,117 @@
+---
+title: Linux Security Hardening Checklist
+audience: human
+last_updated: YYYY-MM-DD
+status: active
+distributable: true
+tags: [security, hardening, linux]
+---
+
+# Linux Security Hardening Checklist
+
+Step-by-step hardening for a Linux host that will run an autonomous agent runtime.
+
+## Executive Summary
+
+- This checklist is the operational sequence for securing a host before production use.
+- It translates threat-model risks into actionable controls with verification steps.
+- Completion status here should be reflected in your security audit log.
+- Use this as an execution checklist, not a conceptual guide.
+
+See also: [Threat Model](threat-model.md), [Authentication Strategy](authentication-strategy.md)
+
+---
+
+## Pre-Checklist: Know Your Environment
+
+- [ ] Confirm OS distribution and version (e.g. `lsb_release -a`)
+- [ ] Confirm kernel version (e.g. `uname -r`)
+- [ ] Document machine hostname (`{HOST}`) and primary user account (`{OPERATOR_USERNAME}`)
+
+---
+
+## 1. System Updates
+
+- [ ] Update all packages (e.g. `sudo apt update && sudo apt upgrade -y`)
+- [ ] Enable unattended security updates so patches land automatically
+
+---
+
+## 2. User & Privilege Management
+
+- [ ] Disable direct root login; use `sudo` only
+- [ ] Audit the sudoers file — confirm only necessary users have sudo
+- [ ] Remove or lock unused accounts
+- [ ] Keep any `NOPASSWD` sudoers exceptions narrowly scoped to a single binary, never a wildcard
+
+---
+
+## 3. SSH (if enabled)
+
+- [ ] Disable password authentication — key-based only
+- [ ] Disable root login over SSH (`PermitRootLogin no`)
+- [ ] Change the default SSH port if externally exposed
+- [ ] Enable a brute-force guard (e.g. fail2ban) if SSH is reachable from untrusted networks
+
+---
+
+## 4. Source Control (Git)
+
+- [ ] Configure an SSH key for your Git host (prefer Ed25519, fall back to RSA 4096 if rejected)
+- [ ] Use SSH remote URLs so credentials are not embedded in URLs or prompted interactively
+- [ ] Keep SSH private keys with mode `600` (`chmod 600 ~/.ssh/id_*`)
+
+---
+
+## 5. Firewall & Network
+
+- [ ] Enable a host firewall (e.g. UFW)
+- [ ] Default deny inbound traffic
+- [ ] Allow only the inbound ports that are strictly required
+- [ ] Enable firewall logging
+
+**Adjacent hosts (general guidance):**
+- [ ] Disable network discovery and file sharing on machines sharing the LAN with the agent host
+Rationale: minimize attack surface, especially with an autonomous agent on the same network. Prefer on-demand, explicit file transfer over always-on sharing.
+
+---
+
+## 6. Drive Protection
+
+- [ ] Ensure foreign/sensitive drives are not auto-mounted (omit from `/etc/fstab`, or list with `noauto`)
+- [ ] Enable full-disk encryption on drives holding sensitive data, so they are unreadable from another OS or a stolen disk
+- [ ] Verify encryption: attempt to mount the encrypted volume from another OS and confirm it fails
+
+### Full-Disk Encryption Notes (general best practices)
+
+- **Never store the only recovery key on the encrypted drive.** Keep it in at least two places: a trusted backup location and an offline printed copy.
+- **Treat boot-partition directories as critical** — deleting boot entries can render the machine unbootable and require recovery media.
+
+---
+
+## 7. Agent Runtime
+
+- [ ] Define which user account the agent runtime runs as — run as a non-root user
+- [ ] Bind the gateway/control plane to loopback only (no LAN exposure)
+- [ ] Authenticate the gateway with a token loaded from an env var / secret manager — never in a committed config file
+- [ ] Set the runtime state directory to mode `700` (user-only)
+- [ ] Remove dead or default-permissive command allow/deny rules left over from onboarding
+- [ ] Run the runtime's security audit and resolve critical findings
+- [ ] Define which directories the runtime has write access to; scope per agent where possible
+- [ ] Define network egress rules — enumerate which external endpoints the runtime may reach
+- [ ] Establish a logging review schedule for agent actions (e.g. spot-check weekly, full review monthly)
+- [ ] Configure tool hardening: deny shell exec where not needed, restrict filesystem scope per agent
+- [ ] Store all API keys via env var / secret manager (mode `600` on any `.env`), never plaintext in config
+
+---
+
+## 8. Remote Access
+
+- [ ] Provide remote access through an encrypted tunnel or VPN rather than open inbound ports
+- [ ] Enable TLS/HTTPS for any remotely reachable endpoint
+- [ ] Review the access list — confirm only expected devices can reach the gateway
+- [ ] Re-verify the device/access list whenever topology changes
+
+---
+
+*Expand each section with the specific commands and verification steps used in your environment, and log completed steps in your security audit log.*

package/dist/assets/.arcane/governance/naming-conventions.md

@@ -0,0 +1,142 @@
+---
+title: Naming Conventions
+audience: both
+last_updated: YYYY-MM-DD
+status: active
+distributable: true
+tags: [naming, convention, machines, agents, identity]
+---
+
+# Naming Conventions
+
+How machines, AI agents, and systems are named across your projects. This is a **template** — adapt the theme and fill in your own roster. Your filled-in instance lives in your ops repo, not here.
+
+## Executive Summary
+
+- Naming is split into three tiers: machines, AI agents, and systems/services.
+- Machine names are iconic identities, agent names are persona-based, and service names are functional.
+- Names must be unique, memorable, and consistent across projects to reduce operational ambiguity.
+- This file is the reference for the patterns and rules; record your actual assigned names in your own ops repo.
+
+---
+
+## Naming Philosophy
+
+Two rules govern every name in the system.
+
+**The Naming Test:** if an established industry term exists for the thing, use the real term — a universe name has to be *earned* by the absence of one. Two dialects result: magic grammar for the personas and vocabulary, plain functional payloads for everything technical. Corollary: the more autonomous the tool, the more boring its name should be.
+
+**The IP rule:** persona names must be **public domain or your own coinage**. No living people. No franchise-coined characters — a borrowed name is owned by whoever coined it, no matter how well it fits. Before any name ships, run the four checks: who coined it; does an estate still do business in it; do same-audience products already claim it (search live — don't trust memory); and what is its first association in each market you operate in, said aloud in every language your team speaks.
+
+Names should be memorable, distinctive, and never repeated across categories.
+
+The naming system has three tiers:
+
+| Category               | What Gets Named                               | Naming Style                                                | Examples                   |
+| ---------------------- | --------------------------------------------- | ----------------------------------------------------------- | -------------------------- |
+| **Machines**           | Physical hardware (PCs, servers, laptops)     | Legendary / iconic figures — the "heavy hitters"            | Atlas, Goliath-class names |
+| **AI Agents**          | Autonomous agents running operations          | Public-domain characters — smart, capable, distinct personality | Merlin, Athena, Prospero   |
+| **Systems / Services** | Databases, APIs, internal tools               | Functional names — clear, descriptive                       | Inventory API, OrderQueue  |
+
+---
+
+## Machines
+
+Machines get the most powerful, iconic names. These are the foundational hardware — they deserve heavyweight identifiers.
+
+| Machine                       | Example Name | Why                                                              |
+| ----------------------------- | ------------ | ---------------------------------------------------------------- |
+| Primary workstation           | **Atlas**    | The one that carries the load — your most powerful build/dev box |
+| Laptop                        | **Voyager**  | The mobile unit that travels with you                           |
+| Secondary / home server       | **Nimbus**   | Always-on node bridging local and cloud environments            |
+
+**Hostname convention:** use the same name everywhere, cased per platform — e.g., Windows hostname `ATLAS`, Linux hostname `atlas`, in documentation `Atlas` (TitleCase).
+
+---
+
+## AI Agents
+
+Agents get persona names paired with a role. The persona name is the primary identifier — what you call it in conversation, logs, and dashboards. The role is metadata that describes what it does.
+
+### Format
+
+```
+[Persona Name] — [Role Title] / [Responsibility Summary]
+```
+
+### Assignment Rules
+
+- One persona name per agent, globally unique across all projects.
+- An agent may serve multiple projects but keeps the same name and role everywhere.
+- If an agent's role changes significantly, it gets a new name (don't reuse names for different roles).
+- If you collaborate with other operators who run their own Arcane instances, reserve names across instances so they don't collide.
+
+### Default Roster (Arcane personas)
+
+Arcane ships with twelve default agent personas, organized by functional cluster. Use them as-is, rename them to your chosen universe, or define your own. The persona definitions live in `.github/agents/` (and `agents/*.yaml`); deployment state (which projects each serves, status, git identity) belongs in your ops repo.
+
+| Persona       | Epithet              | Role                        | Cluster        |
+| ------------- | -------------------- | --------------------------- | -------------- |
+| **Kellar**    | the Maestro          | Product Operations Manager  | Foundation     |
+| **Merlin**    | the Archmage         | CTO / Architecture Lead     | Guide          |
+| **Alexander** | the Man Who Knows    | Research & Backlog Analyst  | Mind           |
+| **Custodio**  | the Warden           | Security Operations         | Bridge         |
+| **Lince**     | the Unmasker         | QA Lead                     | Guardian       |
+| **Mercurio**  | the Swift            | Mobile Developer            | Build Team     |
+| **Adelaide**  | the Illusionist      | Frontend Developer          | Build Team     |
+| **Lafayette** | the Conjuror         | Full-Stack Developer        | Build Team     |
+| **Circe**     | the Charmweaver      | Marketing Strategist        | Voice          |
+| **Bess**      | the Herald           | Operations Communications   | Voice          |
+| **Iris**      | the Emissary         | External Collaboration Lead | Bridge         |
+| **Prospero**  | the Stormcaller      | DevOps / CI/CD Engineer     | Infrastructure |
+
+Twelve legendary agents — the Arcanos. Every namesake is public domain: golden-age stage magicians (Kellar, Lafayette, Adelaide, Alexander, Bess), myth and classic literature (Merlin, Circe, Iris, Prospero, Mercurio), and coinages from living vocabulary (Lince — *ojo de lince*; Custodio — *ángel custodio*). Lince is never anglicized.
+
+**Role consolidation (ADR-031):** Framework-specific dev roles (.NET, Blazor, React, Flutter, MAUI) are consolidated into generic roles (Full-Stack, Frontend, Mobile). The framework/stack is a prompt parameter, not an agent identity. This scales without needing a new agent for every technology.
+
+**Naming policy:** All agent names should be positive characters — beings, not objects — with a clear thematic connection to their role.
+
+**Canonical agent identity domain:** Use a single domain for all agent and tool Git identities — e.g., `merlin@{OPERATOR_DOMAIN}`. See [[DECISIONS#ADR-028|ADR-028]] for the full attribution model.
+
+### Power Levels (ADR-032)
+
+Agent autonomy is assigned per agent × per repo using gamified power levels. See [[DECISIONS#ADR-032|ADR-032]] for full rationale. This is the single canonical ladder — every other document mirrors it. The teachable gradient: **wizards study, sorcerers wield, magi command.**
+
+| Level | Name           | Behavior                                                | Push Model                                  |
+| ----- | -------------- | ------------------------------------------------------- | ------------------------------------------- |
+| 0     | **Spectator**  | Locked — human only                                     | N/A                                         |
+| 1     | **Apprentice** | Agent suggests; human executes                          | Human pushes all                            |
+| 2     | **Wizard**     | Scoped autonomous edits in approved paths               | Agent pushes branch; PRs queued for review  |
+| 3     | **Sorcerer**   | Autonomous topic-branch work                            | Agent pushes and creates PR; human approves |
+| 4     | **Magus**      | Self-merge within approved scope — the "Magus+" gate    | Agent merges (fast-forward only)            |
+| 5     | **Archmage**   | Broadest autonomous authority within an approved repo   | Agent drives; human approves policy changes |
+
+A common starting policy: cap ops/docs repos at **Wizard**, allow app repos up to **Archmage**, and keep repo creation at **Spectator** (human only).
+
+### Name Suggestions (Available Pool)
+
+Every pool entry is public domain and pre-screened against the IP rule. Pick from these when assigning agents, or add your own — after running the four checks.
+
+- **Golden-age magicians (all pre-1955, public domain):** Thurston, Devant, Maskelyne, Talma, Carter, Sherezada
+- **Greek / Egyptian / Ancient Mythology:** Athena, Apollo, Hermes, Orpheus, Horus, Maat, Thoth, Enki, Imhotep
+
+> **Note:** "Pre-screened" is not "cleared forever" — product namespaces shift constantly. Before a pooled name goes onto anything public-facing, re-run the four checks live: coiner, estate, same-audience products, first-association per market.
+
+---
+
+## Systems / Services
+
+Internal tools, databases, APIs, and services use **functional names** — no persona names. These need to be immediately understood by anyone reading a log or config file.
+
+**Format:** `[project-slug]-[function]` or just `[function]` if shared.
+
+**Examples:**
+
+- `acme-store-inventory-api`
+- `widget-co-booking-db`
+- `agent-runtime-monitor`
+- `order-queue`
+
+---
+
+> **Keep your real roster in your ops repo.** This template intentionally omits a live machine inventory, per-agent deployment status, and the naming decisions log — those are operator-specific instance data. Record them alongside your other org docs, not in the distributed framework.

package/dist/assets/.arcane/governance/new-business-setup.md

@@ -0,0 +1,182 @@
+---
+title: New Business Setup Guide
+audience: both
+status: draft
+distributable: true
+tags: [playbook, setup, onboarding, replicability, attribution]
+---
+
+# New Business Setup Guide
+
+The master guide for spinning up a new business ({venture}) under {LLC_NAME} using agent automation.
+
+## Executive Summary
+
+- This playbook is the replication path from idea to operational business environment.
+- It sequences project creation, infrastructure alignment, security prerequisites, and agent readiness.
+- Follow this guide to reduce setup variance and avoid re-solving known operational decisions.
+- Use this as the default onboarding runbook for every new business launch.
+
+**Goal:** Follow this guide once and a new business is fully operational — project, repos, the agent runtime configured, infrastructure documented, legal basics covered.
+
+> **How this guide was built:** Every step here is meant to be done manually at least once for a new {venture}. As steps are validated, they get automated. Check the `scripts/` folder — if a script exists for a step, run the script instead of doing it by hand.
+
+---
+
+## Before You Start
+
+Have the following ready:
+
+- [ ] Business name decided (both brand name and slug, e.g. `{venture}`)
+- [ ] Business type clear (e-commerce, app, protocol, service)
+- [ ] Access to your version-control host / project organization
+- [ ] The agent runtime installed and operational
+- [ ] Full-disk encryption confirmed active on any machine that holds credentials or working copies
+- [ ] System clock correct and time sync enabled. **Critical:** an incorrect system clock breaks all SSL/HTTPS connections silently.
+
+---
+
+## Phase 1 — Project & Repo Setup
+
+### Step 1.1 — Create the Project
+
+1. Open your version-control host's project organization
+2. Create a **New Project**
+3. Name: the business slug (use your org's naming convention)
+4. Description: brief one-liner describing the business
+5. Visibility: **Private**
+6. Version control: **Git**
+7. Work item process: pick your tracker's default (Agile/Scrum/Kanban)
+
+> **Script:** `scripts/create-project.ps1` — automate once the manual steps are validated.
+
+### Step 1.2 — Create Repos
+
+Inside the new project, create repos based on business type:
+
+**E-commerce business:**
+- `storefront` — platform config, theme, automation scripts
+- `inventory` — SKU tracking, reorder logic
+- `marketing` — social content, SEO, copy templates
+
+**App business:**
+- `app` — application code
+- `api` — backend/API
+- `requirements` — specs, wireframes, design docs
+
+**Protocol / whitepaper:**
+- `whitepaper` — the spec document
+
+To create a repo: Project → **Repos** → **New repository** → name → **Create**.
+
+### Step 1.3 — Copy Business Template into Docs Repo
+
+In your docs/ops repo, copy `ventures/_template/` to `ventures/{venture}/` as a **reference hub** and fill in:
+
+- `overview.md` — what the business is, current status, automation scope, blockers
+- links/pointers to the business's dedicated project repos for runtime artifacts
+
+> **Boundary rule:** the ops/docs repo stores shared framework + references. Business runtime artifacts live in business-specific project repos.
+
+---
+
+## Phase 2 — Infrastructure & Security
+
+### Step 2.1 — Confirm Security Baseline
+
+Before running the agent runtime for any new business, verify:
+
+- [ ] Full-disk encryption active on machines holding credentials or working copies
+- [ ] Host hardening checklist complete ([[security/hardening-checklist|Hardening Checklist]])
+- [ ] Agent policies reviewed for this business ([[agents/agent-policies|Agent Policies]])
+- [ ] Runtime hardening enforcement checklist executed
+
+### Step 2.2 — Clone the Docs Repo
+
+```bash
+git clone <docs-repo-url> ~/code/{repo}
+```
+
+---
+
+## Phase 3 — Agent Runtime Configuration
+
+### Step 3.1 — Install the Agent Runtime (if not already installed)
+
+See [[agents/installation|Runtime Installation]].
+
+### Step 3.2 — Configure the Runtime for This Business
+
+- Use the reference template in [[ventures/_template/overview|Business Template]] to capture scope and links
+- Apply business-specific runtime configuration in that business's own project repos and environment
+- Review [[agents/agent-policies|Agent Policies]] — adjust permitted actions if needed for this business type
+
+### Step 3.3 — Agent Git Identity Setup
+
+Every agent that will produce commits for this business must have a registered Git identity **before making its first commit**. See [[governance/git-conventions#agent-attribution-model|Git Conventions — Agent Attribution]].
+
+For each agent assigned to this business:
+
+1. **Confirm persona name** is registered in [[naming-conventions|Naming Conventions]] agent roster.
+2. **Confirm Git identity** exists in the registered identities table in [[governance/git-conventions#agent-email-convention|Git Conventions]].
+3. **Add agent to `.mailmap`** in every repo the agent will commit to:
+   ```
+   {AGENT_NAME} <{AGENT_EMAIL}>
+   ```
+4. **Verify** you can commit with the agent's author:
+   ```bash
+   git commit --allow-empty --author="{AGENT_NAME} <{AGENT_EMAIL}>" \
+     --trailer="Agent=kellar" --trailer="Model=test" --trailer="Provider=test" \
+     -m "test: verify agent git identity for {AGENT_NAME}"
+   git log -1  # confirm author shows {AGENT_NAME}
+   git reset HEAD~1  # clean up test commit
+   ```
+
+### Step 3.4 — Test Run
+
+Run the agent runtime in dry-run / observation mode first. Do not let it execute live actions until you've reviewed its behavior.
+
+---
+
+## Phase 4 — Legal Baseline
+
+### Step 4.1 — Business Entity
+
+- Confirm operations run under {LLC_NAME}
+- If this business has meaningfully different liability exposure (e.g. physical goods vs. software), consult an attorney
+
+### Step 4.2 — Sales Tax (Physical Goods Only)
+
+- Register for sales tax in your home jurisdiction if not already done
+- Identify nexus states based on where you'll sell
+- Configure tax collection on the platform (Shopify, Etsy, etc.)
+
+### Step 4.3 — Platform Terms of Service
+
+- Review the selling platform's ToS for AI-generated listings/content
+- Review your agent runtime's ToS for commercial use
+
+---
+
+## Phase 5 — First Launch Checklist
+
+- [ ] At least 10 product listings live (or equivalent for non-e-commerce)
+- [ ] Order/fulfillment workflow tested end-to-end
+- [ ] The agent runtime running and monitored (see `agents/monitoring.md`)
+- [ ] Legal baseline complete
+- [ ] `ventures/{venture}/overview.md` status updated to reflect live status
+- [ ] Journal entry written in `journal/YYYY-MM-DD-topic-slug.md` documenting launch
+
+---
+
+## What to Automate Next
+
+As you complete this guide manually for each business, flag steps that are repetitive and mechanical. Those become scripts. Priority candidates:
+
+- Project + repo creation (`scripts/create-project.ps1`)
+- Runtime config generation from a template (`scripts/configure-runtime.sh`)
+- Repo initialization with standard folder structure
+
+---
+
+*Fill in this guide as you go. Every blank or TBD here is something you'll encounter during your first {venture} setup — document it then, not in advance.*

package/dist/assets/.arcane/governance/poc-management-pattern.md

@@ -0,0 +1,190 @@
+---
+title: POC Management Pattern
+audience: both
+last_updated: YYYY-MM-DD
+status: active
+distributable: true
+tags: [governance, poc, prototypes, ideas, lifecycle, methodology]
+---
+
+# POC Management Pattern
+
+How ideas move from concept to product. Establishes folder conventions, artifact expectations per stage, iteration tracking, and promotion criteria. Complements the [[governance/development-methodology|Spell Loop]] methodology.
+
+Related: [[governance/development-methodology|Development Methodology]]
+
+---
+
+## Lifecycle Stages
+
+```
+CONCEPT  ──►  PROTOTYPE  ──►  FEATURE  ──►  PRODUCT
+ventures/        Prototypes      features/     business repo
+(docs repo)      (prototypes repo) (code repo)   (code repo)
+```
+
+| Stage | Location | Purpose | Work item? | Code allowed? |
+|---|---|---|---|---|
+| **Concept** | `ventures/<name>/` in the docs repo | Capture and refine an idea. Permanent archive. | No | No |
+| **Prototype** | `<name>/` in the Prototypes repo | Small throwaway demo generated from specs. | No | Yes |
+| **Feature** | `features/{id}-{slug}/` in target code repo | Full Spell Loop execution with planning artifacts. | Yes (tracker) | Yes |
+| **Product** | Target code repo main branch | Shipped, maintained code. Business docs in the docs repo. | Yes (tracker) | Yes |
+
+### Stage Details
+
+#### Concept (`ventures/<name>/`)
+
+The permanent record of every idea — good, bad, or deferred. Ideas are **never deleted**. Frontmatter `status` tracks where each idea is in its lifecycle.
+
+**Required files:**
+- `overview.md` — What is it? Why does it matter? Who is it for? (Minimum viable concept doc.)
+
+**Optional files:**
+- `PRD.md` — If the idea has been through `spell-plan`
+- `architecture.md` — If the idea has been through `spell-architect`
+- `stories.json` — If architecture produced story breakdown
+- Screenshots in `assets/screenshots/YYYY-MM-DD/` (linked from docs)
+
+**What does NOT belong here:** Code files (`.js`, `.ts`, `.py`, `.html`, `.css`, etc.). The docs repo is a documentation-only repository.
+
+#### Prototype (Prototypes repo)
+
+Small, self-contained, throwaway code that demonstrates a concept. Prototypes are **convenience snapshots, not source-of-truth code**. In the vibe coding era, the spec (PRD + architecture) is the reproducible artifact — code can be regenerated from it at any time.
+
+**Required files per prototype:**
+- `README.md` — What it demos + link back to the concept spec in arcane (e.g., `See specs: arcane/ventures/magic-prompt/`)
+- Whatever code files the demo needs
+
+**Folder convention:** `<name>/` at repo root (e.g., `magic-prompt/`, `self-healing-poc/`)
+
+**No governance overhead:** No PRs required, no work items, no branch policies. This is a sandbox. Commit directly to main.
+
+#### Feature (`features/{id}-{slug}/`)
+
+An idea that has entered the [[governance/development-methodology|Spell Loop]] with a tracker work item. Planning artifacts (PRD, architecture, stories.json) live in the target **code repo**, not the docs repo.
+
+#### Product
+
+Feature merged to main and shipped. Business-level documentation lives in `ventures/<name>/` in arcane.
+
+---
+
+## Idea Frontmatter Status
+
+Every file in `ventures/<name>/` uses this frontmatter `status` field:
+
+| Status | Meaning |
+|---|---|
+| `concept` | Captured but not yet explored. Initial state. |
+| `exploring` | Actively being refined — PRD in progress, research happening. |
+| `prototyping` | Code prototype exists in the Prototypes repo. |
+| `promoted` | Entered Spell Loop as a feature in a code repo. Link to tracker work item. |
+| `parked` | Not dead, but not active. May revisit later. |
+| `archived` | Explored and intentionally abandoned. Keep for historical record. |
+
+Set `status` in the overview.md (or PRD.md if that's the primary doc). When an idea is promoted, add `promoted_to` with the target repo and work item:
+
+```yaml
+status: promoted
+promoted_to:
+  repo: "{ORG}/{repo}"
+  work_item: 0
+  date: YYYY-MM-DD
+```
+
+When an idea has a prototype, add `prototype_repo`:
+
+```yaml
+status: prototyping
+prototype_repo: "{ORG}/prototypes"
+prototype_path: magic-prompt
+```
+
+---
+
+## Iteration Tracking
+
+Ideas evolve. Track iterations without complex versioning:
+
+1. **Use the idea's overview.md (or PRD) changelog section.** Add a `## Changelog` heading at the bottom with dated entries:
+   ```markdown
+   ## Changelog
+   - YYYY-MM-DD: Initial concept captured
+   - YYYY-MM-DD: PRD and architecture added (spell-plan + spell-architect)
+   - YYYY-MM-DD: Prototype v1 pushed to Prototypes repo
+   ```
+
+2. **Screenshots:** Save evidence of each meaningful state to `assets/screenshots/YYYY-MM-DD/` per [[assets/screenshots/README|screenshot conventions]]. Link from the changelog.
+
+3. **Git history is the version control.** Don't create `v1/`, `v2/` folders. The idea folder is a living document — git tracks every change.
+
+---
+
+## Promotion Criteria
+
+### Concept → Prototype
+
+No formal gate. If someone (human or agent) wants to see the idea running, generate code from the spec and push to the Prototypes repo. The concept spec in `ventures/` stays as-is.
+
+### Concept/Prototype → Feature
+
+All of these must be true:
+- [ ] A tracker work item exists (User Story or Feature)
+- [ ] A business track owns it (maps to a `ventures/<name>/` folder or a project)
+- [ ] A target code repo exists (or needs to be created; repo creation is human-only)
+- [ ] The idea has at least a PRD (`spell-plan` output)
+
+When promoted: update the idea's frontmatter to `status: promoted` with `promoted_to` metadata. The idea folder stays in arcane forever as the historical record.
+
+### Feature → Product
+
+Standard Spell Loop completion: `spell-implement` → `spell-test` → `spell-review` → `spell-ship`. Feature branch merged to main in the code repo.
+
+---
+
+## Non-Code Ideas
+
+Not every idea needs code. Image projects, design concepts, process improvements, and research topics stay at concept stage permanently. They live in `ventures/<name>/` with an `overview.md` and never need a prototype.
+
+---
+
+## Specs-First Principle
+
+> **The PRD + architecture are the reproducible artifact. Code is ephemeral.**
+
+In the vibe coding era, a well-written spec can regenerate a prototype in minutes. This means:
+- **Invest in the spec**, not the code. A good PRD with clear requirements and a solid architecture doc is worth more than throwaway prototype code.
+- **Don't mourn lost prototypes.** If prototype code is deleted, damaged, or outdated, regenerate it from the spec.
+- **The Prototypes repo is a convenience**, not a vault. It holds the latest snapshot of demo code. It is not versioned, tagged, or released.
+- **When an idea enters the Spell Loop**, the spec travels to the code repo (as `features/{id}-{slug}/PRD.md`). The prototype in the Prototypes repo can be abandoned.
+
+---
+
+## Relationship to Existing Patterns
+
+| Pattern | How it connects |
+|---|---|
+| [[governance/development-methodology\|Spell Loop]] | Ideas enter the loop at `spell-plan`. Concept stage is pre-loop exploration. |
+| Repo routing | Code → code repos. Docs → the docs repo. Prototypes → Prototypes repo. |
+| Repo governance | Repo creation is human-only. Prototypes repo is a single shared repo, not per-POC. |
+| Feature folders | Feature planning artifacts live in the target code repo under `features/`. |
+| `ventures/<name>/` | Business-level docs for shipped products. Ideas that graduate here are fully promoted. |
+
+---
+
+## Quick Reference
+
+**I have a new idea:**
+→ Create `ventures/<name>/overview.md` with `status: concept`
+
+**I want to see it running:**
+→ Generate code from the spec, push to `Prototypes/<name>/` with a README linking to the spec
+
+**I want to build it for real:**
+→ Create a tracker work item, run `spell-plan`, move planning artifacts to target code repo `features/{id}-{slug}/`, update idea status to `promoted`
+
+**The idea didn't work out:**
+→ Set `status: archived` in the idea frontmatter. Add a note explaining why. Keep forever.
+
+**I want to revisit a parked idea:**
+→ Set `status: exploring`, update the changelog, and continue refining the spec