Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
78 commits
Select commit Hold shift + click to select a range
f08aa03
chore(plan): complete planning for PAN-5504
Nov 19, 2026
c0f2715
docs: troubleshooting part A, stale-check section and Vite heading (P…
Nov 19, 2026
fda2066
chore(workspace): plan artifacts for PAN-5504
Nov 19, 2026
2426575
chore(workspace): plan artifacts for PAN-5504
Nov 19, 2026
455eb49
docs: troubleshooting part B, corrupted workspaces, disk low, HTTPS (…
Nov 19, 2026
1c004cd
chore(workspace): plan artifacts for PAN-5504
Nov 19, 2026
ea49256
chore(workspace): plan artifacts for PAN-5504
Nov 19, 2026
0872b74
docs: troubleshooting part C, agent issues, Health page, help sentenc…
Nov 19, 2026
878eced
chore(workspace): plan artifacts for PAN-5504
Nov 19, 2026
02ac3cd
chore(workspace): plan artifacts for PAN-5504
Nov 19, 2026
eabe832
docs: prompts part A, renderPrompt API, real callers, retitle (PAN-5504)
Nov 19, 2026
090167a
chore(workspace): plan artifacts for PAN-5504
Nov 19, 2026
a0271c6
chore(workspace): plan artifacts for PAN-5504
Nov 19, 2026
b7af4ee
docs: prompts part B, frontmatter contract, catalogue, roles (PAN-5504)
Nov 19, 2026
d8062ef
chore(workspace): plan artifacts for PAN-5504
Nov 19, 2026
1a1710c
chore(workspace): plan artifacts for PAN-5504
Nov 19, 2026
a4be889
docs: prompts part C, composition example, tests, troubleshooting (PA…
Nov 19, 2026
59fa2f4
chore(workspace): plan artifacts for PAN-5504
Nov 19, 2026
b9e5af8
chore(workspace): plan artifacts for PAN-5504
Nov 19, 2026
1ce0eed
docs: harness-landscape part A, all ten harnesses, retitle (PAN-5504)
Nov 19, 2026
4fb6d12
chore(workspace): plan artifacts for PAN-5504
Nov 19, 2026
bb45181
chore(workspace): plan artifacts for PAN-5504
Nov 19, 2026
06130f8
docs: harness-landscape part B, profiles, pi default, Codex auth (PAN…
Nov 19, 2026
7a80f14
chore(workspace): plan artifacts for PAN-5504
Nov 19, 2026
8836968
chore(workspace): plan artifacts for PAN-5504
Nov 19, 2026
d616879
docs: harness-landscape part C, matrix, implications, See also (PAN-5…
Nov 19, 2026
80b2b74
chore(workspace): plan artifacts for PAN-5504
Nov 19, 2026
bc8d261
chore(workspace): plan artifacts for PAN-5504
Nov 19, 2026
ab18227
docs: lanes, --force, refusals, lane names, experimental label (PAN-5…
Nov 19, 2026
1e52099
chore(workspace): plan artifacts for PAN-5504
Nov 19, 2026
1bbf308
chore(workspace): plan artifacts for PAN-5504
Nov 19, 2026
e210d83
docs: workers, remote stand-ins, .swarm ignore, external transcripts …
Nov 19, 2026
c8a8f91
chore(workspace): plan artifacts for PAN-5504
Nov 19, 2026
af401eb
chore(workspace): plan artifacts for PAN-5504
Nov 19, 2026
9c7348a
docs: architecture, Effect server, state.json, health monitoring toda…
Nov 19, 2026
f43e6e2
chore(workspace): plan artifacts for PAN-5504
Nov 19, 2026
d99e5c7
chore(workspace): plan artifacts for PAN-5504
Nov 19, 2026
e0f7793
docs: state-model, database-only rows, workspace origin, retitle (PAN…
Nov 19, 2026
4633828
chore(workspace): plan artifacts for PAN-5504
Nov 19, 2026
c231b11
chore(workspace): plan artifacts for PAN-5504
Nov 19, 2026
539e088
docs: god-view, top bar list, orb hover, Escape closes the rail (PAN-…
Nov 19, 2026
f8b18f2
chore(workspace): plan artifacts for PAN-5504
Nov 19, 2026
878a65d
chore(workspace): plan artifacts for PAN-5504
Nov 19, 2026
2658a50
docs: settings, where each setting is saved, Anywhere labels, help (P…
Nov 19, 2026
760873e
chore(workspace): plan artifacts for PAN-5504
Nov 19, 2026
c37f183
chore(workspace): plan artifacts for PAN-5504
Nov 19, 2026
62f400d
docs: docker-setup, current Traefik layout, workspace keys, Vite anch…
Nov 19, 2026
919c3af
chore(workspace): plan artifacts for PAN-5504
Nov 19, 2026
4d4e4eb
chore(workspace): plan artifacts for PAN-5504
Nov 19, 2026
ec0a0c8
docs: legacy-codebases, captured skills, context file, orientation (P…
Nov 19, 2026
3ca24ca
chore(workspace): plan artifacts for PAN-5504
Nov 19, 2026
8097af2
chore(workspace): plan artifacts for PAN-5504
Nov 19, 2026
91c7bca
docs: operating, reload vs restart auto-resume, emergency stop (PAN-5…
Nov 19, 2026
3dde862
chore(workspace): plan artifacts for PAN-5504
Nov 19, 2026
a409818
chore(workspace): plan artifacts for PAN-5504
Nov 19, 2026
14f2bb3
docs: skill-pack-authoring, pack MCP servers, license order, LFS (PAN…
Nov 19, 2026
f34526c
chore(workspace): plan artifacts for PAN-5504
Nov 19, 2026
c47e25e
chore(workspace): plan artifacts for PAN-5504
Nov 19, 2026
e89f8d4
docs: stitch-integration, /stitch-setup, PRD draft instead of STATE.m…
Nov 19, 2026
8c236e8
chore(workspace): plan artifacts for PAN-5504
Nov 19, 2026
fdf1459
chore(workspace): plan artifacts for PAN-5504
Nov 19, 2026
d283fb2
docs: posthog-agents, source maps upload in the pack job (PAN-5504)
Nov 19, 2026
eecb567
chore(workspace): plan artifacts for PAN-5504
Nov 19, 2026
85bc2d4
chore(workspace): plan artifacts for PAN-5504
Nov 19, 2026
96f16f0
docs: template-conversations, what has shipped since the proposal (PA…
Nov 19, 2026
441936b
chore(workspace): plan artifacts for PAN-5504
Nov 19, 2026
b3da366
chore(workspace): plan artifacts for PAN-5504
Nov 19, 2026
283cb8c
docs: agents-directory, experimental wording, stuck definition, retit…
Nov 19, 2026
677e335
chore(workspace): plan artifacts for PAN-5504
Nov 19, 2026
e84673f
chore(workspace): plan artifacts for PAN-5504
Nov 19, 2026
8802f4e
docs: token-spend-report, current report source and figures (PAN-5504)
Nov 19, 2026
d6c5674
chore(workspace): plan artifacts for PAN-5504
Nov 19, 2026
50efc74
chore(workspace): plan artifacts for PAN-5504
Nov 19, 2026
054d14f
docs: validate Guides and Reference audit, draft PR body (PAN-5504)
Nov 19, 2026
276ace4
chore(workspace): plan artifacts for PAN-5504
Nov 19, 2026
b90df2c
chore(workspace): plan artifacts for PAN-5504
Nov 19, 2026
823d784
docs: address CodeRabbit findings on the Guides and Reference audit (…
Nov 19, 2026
f8a7e7b
chore(workspace): record CodeRabbit feedback cycle for PAN-5504
Nov 19, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
568 changes: 568 additions & 0 deletions .pan/continues/PAN-5504.xbrief.json

Large diffs are not rendered by default.

3,138 changes: 3,138 additions & 0 deletions .pan/drafts/PAN-5504.md

Large diffs are not rendered by default.

Large diffs are not rendered by default.

177 changes: 75 additions & 102 deletions guides/docker-setup.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -17,35 +17,31 @@ Overdeck uses Docker for isolated development environments and Traefik as a reve

- Docker Desktop (macOS/Windows) or Docker Engine (Linux)
- Docker Compose v2.x
- `mkcert` for local certificate generation
- `mkcert` for local certificates (`pan install` installs it if it's missing)

## Quick Setup

```bash
# Install mkcert
brew install mkcert # macOS
# or: sudo apt install mkcert # Ubuntu/Debian

# Install the local CA
mkcert -install

# Run Overdeck's setup
pan install
pan doctor # Verify setup
pan install # Docker network, mkcert, local CA, certificates and ~/.overdeck/traefik/
pan doctor # Verify setup
```

`pan install` installs mkcert when it's missing (Homebrew on macOS, a download to `~/.local/bin` on Linux), runs `mkcert -install`, creates the `overdeck` Docker network and writes `~/.overdeck/traefik/`. `--minimal` skips Traefik and mkcert, `--skip-mkcert` skips only the certificates, and `--skip-docker` skips the network.

## Traefik Configuration

Overdeck manages Traefik configuration in `~/.overdeck/traefik/`:

```
~/.overdeck/traefik/
├── docker-compose.yml # Traefik container (traefik:latest, named overdeck-traefik)
├── traefik.yml # Static configuration
├── dynamic/ # Dynamic route configs (per-workspace)
│ └── feature-min-123.yml
└── certs/ # TLS certificates
├── localhost.pem
└── localhost-key.pem
├── dynamic/ # File provider configs
│ ├── overdeck.yml # Dashboard routes
│ └── tls.yml # Every certificate in certs/
└── certs/ # mkcert certificates
├── _wildcard.overdeck.localhost.pem
└── _wildcard.overdeck.localhost-key.pem
```

### Port Binding
Expand Down Expand Up @@ -80,154 +76,129 @@ entryPoints:
scheme: https
websecure:
address: ":443"
http:
tls: {}

providers:
docker:
watch: true
exposedByDefault: false
file:
directory: /etc/traefik/dynamic
watch: true
docker:
endpoint: "unix:///var/run/docker.sock"
exposedByDefault: false
network: overdeck

tls:
stores:
default:
defaultCertificate:
certFile: /certs/localhost.pem
keyFile: /certs/localhost-key.pem
```

### Dynamic Configuration

Each workspace gets a dynamic config file. Example for `feature-min-123`:

```yaml
http:
routers:
feature-min-123-frontend:
rule: "Host(`feature-min-123.localhost`)"
service: feature-min-123-frontend
entryPoints:
- websecure
tls: {}

feature-min-123-api:
rule: "Host(`api-feature-min-123.localhost`)"
service: feature-min-123-api
entryPoints:
- websecure
tls: {}

services:
feature-min-123-frontend:
loadBalancer:
servers:
- url: "http://feature-min-123-frontend:3000"
log:
level: INFO
format: common

feature-min-123-api:
loadBalancer:
servers:
- url: "http://feature-min-123-api:8080"
accessLog:
format: common
```

## Certificate Generation
Certificates aren't in this file: Traefik v3 reads them from `dynamic/tls.yml`. `pan install` copies `traefik.yml` and `docker-compose.yml` only when `~/.overdeck/traefik/docker-compose.yml` doesn't exist yet, so your edits to them are kept.

### Using mkcert
### Dynamic Configuration

```bash
# Generate certificates for localhost domains
cd ~/.overdeck/traefik/certs
mkcert localhost "*.localhost" 127.0.0.1 ::1
Overdeck writes two files in `dynamic/`. `overdeck.yml` routes `https://overdeck.localhost` (the `traefik.domain` value in `~/.overdeck/config.toml`) to the dashboard, and `tls.yml` lists every certificate and key pair in `certs/`. `pan install`, `pan up` and `pan dev` regenerate both. Overdeck doesn't write a dynamic file per workspace: route workspace containers with Docker labels, as in the [Docker Compose Template](#docker-compose-template) below. Traefik also picks up any file you add to `dynamic/` yourself.

# Rename to expected names
mv localhost+3.pem localhost.pem
mv localhost+3-key.pem localhost-key.pem
```
## Certificate Generation

### For Custom Domains
`pan install` writes `_wildcard.overdeck.localhost.pem` and its key to `~/.overdeck/traefik/certs/`. The certificate covers `overdeck.localhost`, `*.overdeck.localhost`, `*.localhost`, `localhost`, `127.0.0.1` and `::1`. `pan install`, `pan up` and `pan dev` also create `_wildcard.<domain>.pem` for each project whose `workspace.dns.domain` is set and has no certificate yet, then rewrite `dynamic/tls.yml`. You don't need to run mkcert yourself.

If using custom domains like `myapp.test`:
To add a certificate by hand, write the pair into the same folder with the key named `<name>-key.pem`. The next `pan up` adds it to `tls.yml`:

```bash
# Generate certificates for custom domain
mkcert myapp.test "*.myapp.test"
cd ~/.overdeck/traefik/certs
mkcert -cert-file _wildcard.myapp.test.pem -key-file _wildcard.myapp.test-key.pem myapp.test "*.myapp.test"
```

## DNS Configuration

### Option 1: .localhost (Recommended)

Modern browsers resolve `*.localhost` to `127.0.0.1` automatically. No DNS config needed.
Modern browsers resolve `*.localhost` to `127.0.0.1` automatically, so `.localhost` hostnames need no `workspace.dns` block. Without one, templates get `{{DOMAIN}}` set to `localhost`.

### Option 2: /etc/hosts

For a custom domain, add a `workspace.dns` block to the project in `~/.overdeck/projects.yaml`:

```yaml
# In projects.yaml
dns:
domain: localhost
entries:
- "{{FEATURE_FOLDER}}.localhost"
- "api-{{FEATURE_FOLDER}}.localhost"
projects:
myapp:
workspace:
dns:
domain: myapp.test
entries:
- "{{FEATURE_FOLDER}}.{{DOMAIN}}"
- "api-{{FEATURE_FOLDER}}.{{DOMAIN}}"
sync_method: hosts_file
```

### Option 2: /etc/hosts

For custom domains, add entries to `/etc/hosts`:
When it creates a workspace, Overdeck adds each entry as a `127.0.0.1` line inside a `# BEGIN overdeck managed entries` block in `/etc/hosts`, and removes it when the workspace is removed. The Overdeck process must be able to write `/etc/hosts`. If it can't, the entry is skipped without an error, so add the lines by hand:

```bash
# Add manually or let Overdeck manage it
127.0.0.1 feature-min-123.myapp.test
127.0.0.1 api-feature-min-123.myapp.test
```

`sync_method: dnsmasq` writes `address=/<host>/127.0.0.1` lines to `overdeck.conf` in `/etc/dnsmasq.d` (Homebrew's `etc/dnsmasq.d` on macOS) instead. When `sync_method` is unset, Overdeck uses `wsl2hosts`.

### Option 3: WSL2 Hosts Sync (Windows)

For WSL2, use the `wsl2hosts` sync method:
For WSL2, use the `wsl2hosts` sync method (also the default when `sync_method` is unset):

```yaml
dns:
sync_method: wsl2hosts
```

This syncs entries between WSL2's `/etc/hosts` and Windows' hosts file.
Overdeck appends each hostname to `~/.wsl2hosts` and starts the Windows scheduled task `OverdeckWsl2HostsSync`, which copies the entries into the Windows hosts file. Register that task once, from an Administrator PowerShell, with the scripts in [`infra/wsl2hosts`](https://github.com/eltmon/overdeck/tree/main/infra/wsl2hosts).

## Starting Traefik

### Via Dashboard
### With pan up

The dashboard starts Traefik automatically when you run `pan up`:
`pan up` starts Traefik when `traefik.enabled` is true in `~/.overdeck/config.toml`. `pan install` sets it unless you pass `--minimal`, and `pan up --skip-traefik` skips the start:

```bash
pan up
# Traefik available at http://localhost:8080 (dashboard)
# HTTPS routing at https://*.localhost
# Dashboard at https://overdeck.localhost
```

### Manually

```bash
# Start Traefik container
docker run -d \
--name overdeck-traefik \
--network overdeck \
-p 80:80 -p 443:443 -p 8080:8080 \
-v /var/run/docker.sock:/var/run/docker.sock:ro \
-v ~/.overdeck/traefik:/etc/traefik:ro \
-v ~/.overdeck/traefik/certs:/certs:ro \
traefik:v2.10
cd ~/.overdeck/traefik
docker compose up -d
```

`pan restart --traefik` recreates the container with the current compose file.

## Workspace Container Setup

### Docker Compose Template

Point `workspace.docker.compose_template` in `~/.overdeck/projects.yaml` at a template folder in your project. When Overdeck creates a workspace, it renders every `*.template` file in that folder into `<workspace>/.devcontainer/` (replacing placeholders such as `{{FEATURE_FOLDER}}`) and copies the other files as they are. It starts the stack only when asked, for example with `pan workspace create <issueId> --docker`. Re-render with `pan workspace render-devcontainer <featureName>`, or tear down, re-render and restart one stack with `pan workspace rebuild <issueId>`.

```yaml
projects:
myapp:
workspace:
docker:
compose_template: infra/.devcontainer-template
```

```yaml
# infra/.devcontainer-template/docker-compose.yml.template
services:
frontend:
build:
context: ./fe
context: ../fe
dockerfile: Dockerfile
volumes:
- ./fe:/app
- ../fe:/app
labels:
- "traefik.enable=true"
- "traefik.http.routers.{{FEATURE_FOLDER}}-fe.rule=Host(`{{FEATURE_FOLDER}}.localhost`)"
Expand All @@ -239,10 +210,10 @@ services:

api:
build:
context: ./api
context: ../api
dockerfile: Dockerfile
volumes:
- ./api:/app
- ../api:/app
labels:
- "traefik.enable=true"
- "traefik.http.routers.{{FEATURE_FOLDER}}-api.rule=Host(`api-{{FEATURE_FOLDER}}.localhost`)"
Expand All @@ -259,7 +230,7 @@ networks:

### Network Setup

Create the shared Overdeck network:
`pan install` creates the shared `overdeck` network. To create it by hand:

```bash
docker network create overdeck
Expand Down Expand Up @@ -325,6 +296,8 @@ lsof -i :443

See [Troubleshooting](/reference/troubleshooting#wsl2-stability-issues-windows-users) for WSL2-specific networking and performance issues.

Still stuck? Ask on the [Overdeck Discord](https://discord.gg/ZpHE2ZTv5P) or file a [GitHub Issue](https://github.com/eltmon/overdeck/issues).

## Best Practices

### Resource Management
Expand All @@ -342,7 +315,7 @@ See [Troubleshooting](/reference/troubleshooting#wsl2-stability-issues-windows-u
### Performance

- **Use Docker volumes for node_modules** - Avoid mounting from host
- **Adjust Vite polling interval** - See [Troubleshooting](/reference/troubleshooting#slow-vitereact-frontend-with-multiple-workspaces)
- **Adjust Vite polling interval**: see [Troubleshooting](/reference/troubleshooting#slow-vite-and-react-frontend-with-multiple-workspaces)
- **Monitor container resources** - Use `docker stats`

## Related Guides
Expand Down
28 changes: 15 additions & 13 deletions guides/legacy-codebases.mdx
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: Legacy Codebase Support
description: AI-powered development for enterprise legacy systems
description: "Teach agents your legacy codebase: Knowledge Capture saves corrections as project skills, and Refactor Radar proposes fixes for confusing code."
---

# Legacy Codebase Support
Expand Down Expand Up @@ -60,12 +60,12 @@ Session 5: Refactor Radar detects: "Same entity called 'user', 'account', 'membe

**When one developer learns, everyone benefits.**

Captured skills live in your project's `.claude/skills/` directory - they're version-controlled alongside your code. When Sarah documents that "we use camelCase columns" after hitting that error, every developer on the team - and every AI session from that point forward - inherits that knowledge automatically.
Knowledge Capture writes captured skills to `.claude/skills/project-knowledge/SKILL.md` in the repository you're working in. Overdeck adds `.claude/skills/` to a project's `.gitignore` when it creates a workspace, so that file stays on your machine. To share it, move it to `.pan/skills/project-knowledge/SKILL.md` and commit it. Overdeck copies `.pan/skills/` into each new issue workspace, so when Sarah commits that "we use camelCase columns", every developer's next workspace inherits it. See [Project skills](/features/skills#project-skills).

```
myproject/
├── .claude/skills/
│ └── project-knowledge/ # ← Git-tracked, shared by entire team
├── .pan/skills/
│ └── project-knowledge/ # Git-tracked, shared by the team
│ └── SKILL.md # "Database uses camelCase, not snake_case"
├── src/
└── ...
Expand All @@ -77,11 +77,7 @@ No more repeating the same corrections to AI across 10 different developers. No

## For Technical Leaders

**What gets measured gets managed.** Overdeck's Refactor Radar surfaces the specific patterns that are costing you AI productivity:

- "Here are the 5 naming inconsistencies causing 40% of AI errors"
- "These 3 missing FK constraints led to 12 incorrect deletions last month"
- "Mixed async patterns in payments module caused 8 rollbacks"
Refactor Radar names the patterns that keep confusing AI in your codebase: one entity called `user`, `account` and `member` across layers, a relationship with no foreign key constraint, or callbacks, promises and async/await mixed in one module. It doesn't count errors or measure what they cost.

Each proposal includes:
- **Evidence**: Specific file paths and examples
Expand All @@ -100,16 +96,16 @@ Overdeck's learning system:
- Captures corrections once, applies them forever
- Identifies root causes (not just symptoms)
- Creates actionable improvement proposals
- Works across your entire AI toolchain (Claude, Codex, Cursor, Gemini)
- Works in every harness `pan sync` installs skills for: Claude Code, plus Codex and Pi through `~/.agents/skills`

**This isn't "AI for greenfield only." This is AI that learns your business.**

## Configurable Per Team and Per Developer

Different teams have different ownership boundaries. Individual developers have different preferences. Overdeck respects both:
Each developer lists the categories to skip or welcome in their own global context file, and each project can tune how often the skills ask in `.overdeck/knowledge-capture.json` and `.overdeck/refactor-radar.json`:

```markdown
# In ~/.claude/CLAUDE.md (developer's personal config)
# In ~/.overdeck/context/global.md (open it with: pan context edit)

## AI Suggestion Preferences

Expand All @@ -127,8 +123,14 @@ skip: authentication # Security team owns this

The AI adapts to your org structure, not the other way around.

## Give agents a map and the rules up front

- **Codebase map.** The `/pan-map` skill writes four orientation files under `.overdeck/context/codebase/`: `architecture.md`, `conventions.md`, `concerns.md` and `stack.md`. Commit them. Planning agents read them first and write them when they're missing; work agents skim them before they start.
- **Project rules.** `pan context edit --layer project` opens `.overdeck/context/project.md`, the committed project layer. See [Context layers](/configuration/context-layers).
- **Memory facts.** Record a rule every agent must follow with `pan memory add <id>`; see [Memory](/configuration/memory) for its type, description and body options. Overdeck renders the fact index into each managed agent's launch context.

## Related Guides

- [Knowledge Capture Skill](/features/skills#ai-self-monitoring) - Capturing learnings automatically
- [Refactor Radar Skill](/features/skills#ai-self-monitoring) - Detecting systemic issues
- [Project Skills](/features/skills#creating-custom-skills) - Creating project-specific knowledge
- [Project Skills](/features/skills#project-skills) - Sharing project-specific knowledge through `.pan/skills/`
Loading
Loading