Merge pull request coleam00#981 from dynamous-community/feat/move-docs-to-workspace

refactor: move docs site to packages/docs-web as workspace member

Author: Wirasm

.claude/rules/dx-quirks.md

@@ -0,0 +1,22 @@
+# DX Quirks
+
+## Bun Log Elision
+
+When running `bun dev` from repo root, `--filter` truncates logs to `[N lines elided]`.
+To see full logs: `cd packages/server && bun --watch src/index.ts` or `bun --cwd packages/server run dev`.
+
+## mock.module() Pollution
+
+`mock.module()` is process-global and irreversible — `mock.restore()` does NOT undo it.
+Never add `afterAll(() => mock.restore())` for `mock.module()` cleanup.
+Use `spyOn()` for internal modules (spy.mockRestore() DOES work).
+When adding tests with `mock.module()`, ensure package.json runs it in a separate `bun test` invocation.
+
+## Worktree Port Allocation
+
+Worktrees auto-allocate ports (3190-4089 range, hash-based on path). Same worktree always gets same port.
+Main repo defaults to 3090. Override: `PORT=4000 bun dev`.
+
+## bun run test vs bun test
+
+NEVER run `bun test` from repo root — it discovers all test files across packages in one process, causing ~135 mock pollution failures. Always use `bun run test` (which uses `bun --filter '*' test` for per-package isolation).

.claude/rules/isolation-patterns.md

@@ -0,0 +1,39 @@
+# Isolation Architecture Patterns
+
+## Core Design
+
+- ALL isolation logic is centralized in the orchestrator — adapters are thin
+- Every @mention auto-creates a worktree (simplicity > efficiency; worktrees are cheap)
+- Data model is work-centric (`isolation_environments` table), enabling cross-platform sharing
+- Cleanup is a separate service using git-first checks
+
+## Directory Structure
+
+```
+~/.archon/workspaces/owner/repo/
+├── source/          # Clone or symlink to local path
+├── worktrees/       # Git worktrees for this project
+├── artifacts/       # Workflow artifacts (NEVER in git)
+│   └── runs/{id}/   # Per-run artifacts ($ARTIFACTS_DIR)
+└── logs/            # Workflow execution logs
+```
+
+## Resolution Flow
+
+1. Adapter provides `IsolationHints` (conversationId, workflowId, branch preference)
+2. Orchestrator's `validateAndResolveIsolation()` resolves hints → environment
+3. WorktreeProvider creates worktree if needed, syncs with origin first
+4. Environment tracked in `isolation_environments` table
+
+## Key Packages
+
+- `@archon/isolation` (`packages/isolation/src/`) — types, providers, resolver, error classifiers
+- `@archon/git` (`packages/git/src/`) — branch, worktree, repo operations
+- `@archon/paths` (`packages/paths/src/`) — path resolution utilities
+
+## Safety Rules
+
+- NEVER run `git clean -fd` — permanently deletes untracked files
+- Use `classifyIsolationError()` to map git errors to user-friendly messages
+- Trust git's natural guardrails (refuse to remove worktree with uncommitted changes)
+- Use `execFileAsync` (not `exec`) when calling git directly

.github/workflows/deploy-docs.yml

@@ -3,7 +3,7 @@ name: Deploy Docs
 on:
   push:
     branches: [main]
-    paths: ['website/**']
+    paths: ['packages/docs-web/**']
   workflow_dispatch:
 
 permissions:
@@ -20,15 +20,17 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: withastro/action@v3
+      - uses: oven-sh/setup-bun@v2
         with:
-          path: ./website
-          node-version: 22
-          package-manager: npm@11
+          bun-version: 1.3.11
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+      - name: Build docs
+        run: bun run build:docs
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          path: ./website/dist
+          path: ./packages/docs-web/dist
 
   deploy:
     needs: build

.prettierignore

@@ -28,7 +28,7 @@ package-lock.json
 .archon/
 
 # Website (Astro/Starlight - uses own formatting)
-website/
+packages/docs-web/
 
 # GitHub templates (don't auto-format)
 .github/

CLAUDE.md

@@ -656,7 +656,7 @@ async function createSession(conversationId: string, codebaseId: string) {
 2. **Workflows** (YAML-based):
    - Stored in `.archon/workflows/` (searched recursively)
    - Multi-step AI execution chains, discovered at runtime
-   - **`nodes:` (DAG format)**: Nodes with explicit `depends_on` edges; independent nodes in the same topological layer run concurrently. Node types: `command:` (named command file), `prompt:` (inline prompt), `bash:` (shell script, stdout captured as `$nodeId.output`, no AI), `loop:` (iterative AI prompt until completion signal) — see docs/loop-nodes.md. Supports `when:` conditions, `trigger_rule` join semantics, `$nodeId.output` substitution, `output_format` for structured JSON output (Claude and Codex), `allowed_tools`/`denied_tools` for per-node tool restrictions (Claude only), `hooks` for per-node SDK hook callbacks (Claude only) — see docs/hooks.md, `mcp` for per-node MCP server config files (Claude only, env vars expanded at execution time) — see docs/mcp-servers.md, and `skills` for per-node skill preloading via AgentDefinition wrapping (Claude only) — see docs/skills.md
+   - **`nodes:` (DAG format)**: Nodes with explicit `depends_on` edges; independent nodes in the same topological layer run concurrently. Node types: `command:` (named command file), `prompt:` (inline prompt), `bash:` (shell script, stdout captured as `$nodeId.output`, no AI), `loop:` (iterative AI prompt until completion signal) . Supports `when:` conditions, `trigger_rule` join semantics, `$nodeId.output` substitution, `output_format` for structured JSON output (Claude and Codex), `allowed_tools`/`denied_tools` for per-node tool restrictions (Claude only), `hooks` for per-node SDK hook callbacks (Claude only), `mcp` for per-node MCP server config files (Claude only, env vars expanded at execution time), and `skills` for per-node skill preloading via AgentDefinition wrapping (Claude only)
    - Provider inherited from `.archon/config.yaml` unless explicitly set; per-node `provider` and `model` overrides supported
    - Model and options can be set per workflow or inherited from config defaults
    - `interactive: true` at the workflow level forces foreground execution on web (required for approval-gate workflows in the web UI)
@@ -678,7 +678,7 @@ async function createSession(conversationId: string, codebaseId: string) {
 **Global workflows** (user-level, applies to every project):
 - Path: `~/.archon/.archon/workflows/` (or `$ARCHON_HOME/.archon/workflows/`)
 - Load priority: bundled < global < repo-specific (repo overrides global by filename)
-- See `docs/global-workflows.md` for details
+- See the docs site at `packages/docs-web/` for details
 
 ### Error Handling