feat: triage workspace + PAT auth + upgrade infrastructure + seed dataset + OpenAPI hardening

.beads/.gitignore

@@ -0,0 +1,70 @@
+# Dolt database (managed by Dolt, not git)
+dolt/
+embeddeddolt/
+
+# Runtime files
+bd.sock
+bd.sock.startlock
+sync-state.json
+last-touched
+.exclusive-lock
+
+# Daemon runtime (lock, log, pid)
+daemon.*
+
+# Push state (runtime, per-machine)
+push-state.json
+
+# Lock files (various runtime locks)
+*.lock
+
+# Credential key (encryption key for federation peer auth — never commit)
+.beads-credential-key
+
+# Local version tracking (prevents upgrade notification spam after git ops)
+.local_version
+
+# Worktree redirect file (contains relative path to main repo's .beads/)
+# Must not be committed as paths would be wrong in other clones
+redirect
+
+# Sync state (local-only, per-machine)
+# These files are machine-specific and should not be shared across clones
+.sync.lock
+export-state/
+export-state.json
+
+# Ephemeral store (SQLite - wisps/molecules, intentionally not versioned)
+ephemeral.sqlite3
+ephemeral.sqlite3-journal
+ephemeral.sqlite3-wal
+ephemeral.sqlite3-shm
+
+# Dolt server management (auto-started by bd)
+dolt-server.pid
+dolt-server.log
+dolt-server.lock
+dolt-server.port
+dolt-server.activity
+
+# Corrupt backup directories (created by bd doctor --fix recovery)
+*.corrupt.backup/
+
+# Backup data (auto-exported JSONL, local-only)
+backup/
+
+# Per-project environment file (Dolt connection config, GH#2520)
+.env
+
+# Legacy files (from pre-Dolt versions)
+*.db
+*.db?*
+*.db-journal
+*.db-wal
+*.db-shm
+db.sqlite
+bd.db
+# NOTE: Do NOT add negation patterns here.
+# They would override fork protection in .git/info/exclude.
+# Config files (metadata.json, config.yaml) are tracked by git by default
+# since no pattern above ignores them.

.beads/README.md

@@ -0,0 +1,81 @@
+# Beads - AI-Native Issue Tracking
+
+Welcome to Beads! This repository uses **Beads** for issue tracking - a modern, AI-native tool designed to live directly in your codebase alongside your code.
+
+## What is Beads?
+
+Beads is issue tracking that lives in your repo, making it perfect for AI coding agents and developers who want their issues close to their code. No web UI required - everything works through the CLI and integrates seamlessly with git.
+
+**Learn more:** [github.com/steveyegge/beads](https://github.com/steveyegge/beads)
+
+## Quick Start
+
+### Essential Commands
+
+```bash
+# Create new issues
+bd create "Add user authentication"
+
+# View all issues
+bd list
+
+# View issue details
+bd show <issue-id>
+
+# Update issue status
+bd update <issue-id> --claim
+bd update <issue-id> --status done
+
+# Sync with Dolt remote
+bd dolt push
+```
+
+### Working with Issues
+
+Issues in Beads are:
+- **Git-native**: Stored in Dolt database with version control and branching
+- **AI-friendly**: CLI-first design works perfectly with AI coding agents
+- **Branch-aware**: Issues can follow your branch workflow
+- **Always in sync**: Auto-syncs with your commits
+
+## Why Beads?
+
+✨ **AI-Native Design**
+- Built specifically for AI-assisted development workflows
+- CLI-first interface works seamlessly with AI coding agents
+- No context switching to web UIs
+
+🚀 **Developer Focused**
+- Issues live in your repo, right next to your code
+- Works offline, syncs when you push
+- Fast, lightweight, and stays out of your way
+
+🔧 **Git Integration**
+- Automatic sync with git commits
+- Branch-aware issue tracking
+- Dolt-native three-way merge resolution
+
+## Get Started with Beads
+
+Try Beads in your own projects:
+
+```bash
+# Install Beads
+curl -sSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
+
+# Initialize in your repo
+bd init
+
+# Create your first issue
+bd create "Try out Beads"
+```
+
+## Learn More
+
+- **Documentation**: [github.com/steveyegge/beads/docs](https://github.com/steveyegge/beads/tree/main/docs)
+- **Quick Start Guide**: Run `bd quickstart`
+- **Examples**: [github.com/steveyegge/beads/examples](https://github.com/steveyegge/beads/tree/main/examples)
+
+---
+
+*Beads: Issue tracking that moves at the speed of thought* ⚡

.beads/config.yaml

@@ -0,0 +1,57 @@
+# Beads Configuration File
+# This file configures default behavior for all bd commands in this repository
+# All settings can also be set via environment variables (BD_* prefix)
+# or overridden with command-line flags
+
+# Issue prefix for this repository (used by bd init)
+# If not set, bd init will auto-detect from directory name
+# Example: issue-prefix: "myproject" creates issues like "myproject-1", "myproject-2", etc.
+# issue-prefix: ""
+
+# Use no-db mode: JSONL-only, no Dolt database
+# When true, bd will use .beads/issues.jsonl as the source of truth
+# no-db: false
+
+# Enable JSON output by default
+# json: false
+
+# Feedback title formatting for mutating commands (create/update/close/dep/edit)
+# 0 = hide titles, N > 0 = truncate to N characters
+# output:
+#   title-length: 255
+
+# Default actor for audit trails (overridden by BEADS_ACTOR or --actor)
+# actor: ""
+
+# Export events (audit trail) to .beads/events.jsonl on each flush/sync
+# When enabled, new events are appended incrementally using a high-water mark.
+# Use 'bd export --events' to trigger manually regardless of this setting.
+# events-export: false
+
+# Multi-repo configuration (experimental - bd-307)
+# Allows hydrating from multiple repositories and routing writes to the correct database
+# repos:
+#   primary: "."  # Primary repo (where this database lives)
+#   additional:   # Additional repos to hydrate from (read-only)
+#     - ~/beads-planning  # Personal planning repo
+#     - ~/work-planning   # Work planning repo
+
+# JSONL backup (periodic export for off-machine recovery)
+# Auto-enabled when a git remote exists. Override explicitly:
+# backup:
+#   enabled: false     # Disable auto-backup entirely
+#   interval: 15m      # Minimum time between auto-exports
+#   git-push: false    # Disable git push (export locally only)
+#   git-repo: ""       # Separate git repo for backups (default: project repo)
+
+# Integration settings (access with 'bd config get/set')
+# Non-secret keys (stored in the database):
+# - jira.url, jira.project
+# - linear.team_id
+# - github.org, github.repo
+#
+# Secret keys (stored in this file but prefer env vars to avoid git exposure):
+# - linear.api_key  → use LINEAR_API_KEY env var instead
+# - github.token    → use GITHUB_TOKEN env var instead
+
+sync.remote: "git+https://github.com/mitre/vulcan.git"

.beads/metadata.json

@@ -0,0 +1,7 @@
+{
+  "database": "dolt",
+  "backend": "dolt",
+  "dolt_mode": "server",
+  "dolt_database": "vulcan_v2",
+  "project_id": "cb49a1de-7945-4a6b-9c30-2cca1bdbe6dc"
+}

.env.example

@@ -12,15 +12,12 @@
 #
 # DATABASE_PORT=5432
 # DATABASE_HOST=127.0.0.1
+# DATABASE_NAME=vulcan_development   # dev + production only; test is hardcoded (vulcan_test)
 # POSTGRES_PORT=5432
 #
 # macOS with Kerberos/GSSAPI connection errors (corporate networks):
 # DATABASE_GSSENCMODE=disable
 #
-# Worktree isolation: suffix appended to database names in database.yml
-# Each worktree gets its own database (e.g., vulcan_vue_development_v2)
-# DB_SUFFIX=_v2
-#
 # App server port (Puma):
 # PORT=3000
 
@@ -159,6 +156,19 @@ VULCAN_CONSENT_TTL=0
 # VULCAN_PASSWORD_MIN_NUMBER=2
 # VULCAN_PASSWORD_MIN_SPECIAL=2
 
+# =============================================================================
+# API TOKENS — Personal Access Tokens for programmatic API access
+# =============================================================================
+# Enable/disable the PAT feature entirely. When false, token management
+# endpoints return 404 and Authorization: Token headers are ignored.
+VULCAN_API_TOKENS_ENABLED=true
+# Maximum number of active (non-revoked) tokens per user
+# VULCAN_API_TOKENS_MAX_PER_USER=20
+# Maximum token lifetime in days (enforced on creation)
+# VULCAN_API_TOKENS_MAX_LIFETIME_DAYS=365
+# Auto-revoke tokens unused for this many days (rake api_tokens:revoke_idle)
+# VULCAN_API_TOKENS_AUTO_REVOKE_IDLE_DAYS=90
+
 # =============================================================================
 # SLACK INTEGRATION (Optional)
 # =============================================================================

.eslintrc.js

@@ -1,9 +1,14 @@
+const rulesDirPlugin = require("eslint-plugin-rulesdir");
+
+rulesDirPlugin.RULES_DIR = "eslint-rules";
+
 module.exports = {
   env: {
     browser: true,
     es6: true,
     node: true,
   },
+  plugins: ["rulesdir"],
   extends: ["plugin:vue/recommended", "prettier", "plugin:prettier/recommended"],
   ignorePatterns: [
     "docs/.vitepress/cache/**",
@@ -16,6 +21,7 @@ module.exports = {
     "no-console": "warn",
     "no-return-await": "warn",
     "no-throw-literal": "warn",
+    "rulesdir/comment-tracker": "error",
     "vue/require-default-prop": "off",
     "vue/prop-name-casing": "off",
     "vue/multi-word-component-names": "off",

.github/workflows/docs.yml

@@ -7,6 +7,8 @@ on:
       - main
     paths:
       - 'docs/**'
+      - 'doc/openapi.yaml'
+      - 'doc/openapi/**'
       - '.github/workflows/docs.yml'
   workflow_dispatch:
 
@@ -38,13 +40,20 @@ jobs:
       - name: Setup Pages
         uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
 
+      - name: Install root dependencies (for redocly CLI)
+        run: yarn install --frozen-lockfile
+
+      - name: Generate OpenAPI JSON for docs
+        run: yarn openapi:docs
+
       - name: Install and build docs
         env:
           GITHUB_DEPLOY: "true"  # Tell VitePress to use / base for custom domain
         run: |
-          # DO NOT install main dependencies - they cause Vue 2/3 conflict
+          # Docs have their own package.json with Vue 3 deps (isolated from
+          # the Rails app's Vue 2). Install only docs deps in CI.
           cd docs
-          yarn install
+          yarn install --frozen-lockfile
           yarn build
 
       - name: Upload artifact

.github/workflows/release.yml

@@ -51,3 +51,25 @@ jobs:
           image: mitre/vulcan:${{ steps.meta.outputs.version }}
           artifact-name: image.spdx.json
           dependency-snapshot: true
+
+  # ─── OPENAPI REGISTRY PUBLISH ───
+  openapi-publish:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 5
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 1
+
+      - name: Publish OpenAPI spec to Scalar registry
+        run: |
+          npx @scalar/cli auth login --token "$SCALAR_TOKEN"
+          npx @scalar/cli registry publish doc/openapi.yaml \
+            --namespace mitre \
+            --slug vulcan \
+            --version "${{ github.event.release.tag_name }}" \
+            --force
+        env:
+          SCALAR_TOKEN: ${{ secrets.SCALAR_REGISTRY_TOKEN }}

.gitignore

@@ -81,11 +81,19 @@ AGENT-STATUS/
 /app/assets/builds/*
 !/app/assets/builds/.keep
 .beads/recovery-context.md
+.beads/recovery-prompt.md
+.beads/dolt-backup*
 
 # Beads / Dolt files (added by bd init)
 .dolt/
 *.db
 .beads-credential-key
-# Beads auto-exports the entire issues database to issues.jsonl on each
-# bd write — local-only artifact, not meant for git.
+# Beads auto-exports to issues.jsonl on each bd write.
+# The .beads/ copy is tracked for team visibility.
 issues.jsonl
+!.beads/issues.jsonl
+# interactions.jsonl is session-local chat history — not shared
+.beads/interactions.jsonl
+
+# Local build / tool caches (yarn, corepack, node) when running outside Docker
+/.cache/