@stravica-ai/digital-operator-pa 0.1.0

package/dist/engineering-pa-cli/src/sync/runs-digest.mjs

@@ -0,0 +1,138 @@
+// sync — digest the cron tools' runs.jsonl files.
+//
+// At commit time, sync composes a commit-message body that summarises
+// what's being captured: which tools ran, with what status, how recently.
+// The body is parsed from the last few records of each known tool's
+// runs.jsonl file. This makes `git log` of sync commits self-describing —
+// "this is what wsd-ingest produced at HH:MM:SS"-style.
+//
+// In v2 the operator repo no longer contains `core/tools/`. Platform-shipped
+// tools (distill, memory-sync, etc.) write their audit logs under
+// `<repoRoot>/.cache/<tool>/logs/runs.jsonl`. Operator-extension tools keep
+// writing under `<repoRoot>/operator/extensions/tools/<tool>/logs/runs.jsonl`.
+// Discovery walks both parents.
+//
+// Per the scheduled-tool audit-record contract (§15 of the tooling
+// standard) every record carries `ts` (RFC-3339) and `status`. We tolerate
+// missing fields gracefully — an old-format line still gets surfaced.
+
+// Directory discovery is by explicit walk over known parents — node:fs's
+// glob is recent and not yet supported across all Node LTSes we target,
+// and `readdir` is well-known and portable.
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+
+// In v2 the KNOWN_PARENTS pair the package's audit-log convention
+// (`.cache/<tool>/logs/runs.jsonl`) with operator-extension tooling
+// (`operator/extensions/tools/<tool>/logs/runs.jsonl`). The v1 entry
+// `core/tools` is dropped — that tree no longer exists in operator repos.
+export const KNOWN_PARENTS = [
+  '.cache',
+  'operator/extensions/tools',
+];
+
+export async function discoverToolRunsLogs(repoRoot, { extraParents = [] } = {}) {
+  const out = [];
+  const parents = [...KNOWN_PARENTS, ...extraParents];
+  for (const parent of parents) {
+    const parentAbs = join(repoRoot, parent);
+    let entries;
+    try {
+      entries = await readdir(parentAbs, { withFileTypes: true });
+    } catch (err) {
+      if (err.code === 'ENOENT') continue;
+      throw err;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      // Skip the sync tool itself — we don't want our own audit log
+      // showing up in the digest. Skip both the current cache dir name
+      // (estate-sync) and the pre-rename name (sync) — a host upgraded
+      // in place may still have an orphaned `.cache/sync/` directory.
+      if (entry.name === 'estate-sync' || entry.name === 'sync') continue;
+      const candidate = join(parentAbs, entry.name, 'logs', 'runs.jsonl');
+      try {
+        await readFile(candidate, 'utf8');
+        out.push({ tool: entry.name, parent, path: candidate });
+      } catch (err) {
+        // Tool exists but no logs/runs.jsonl yet — skip.
+        if (err.code !== 'ENOENT' && err.code !== 'EISDIR') throw err;
+      }
+    }
+  }
+  return out;
+}
+
+// Read the last `n` non-empty lines of a file. The runs.jsonl files are
+// small (KB, not MB) so reading the whole file is fine and simpler than
+// reverse-seeking.
+export async function tailJsonl(path, n) {
+  let content;
+  try {
+    content = await readFile(path, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return [];
+    throw err;
+  }
+  const lines = content.split('\n').filter((l) => l.trim().length > 0);
+  const tail = lines.slice(Math.max(0, lines.length - n));
+  return tail
+    .map((line) => {
+      try {
+        return JSON.parse(line);
+      } catch {
+        return null;
+      }
+    })
+    .filter((r) => r !== null);
+}
+
+// Compose a multi-line commit-message body summarising recent activity
+// across the discovered tools. The body is intentionally terse — diffs in
+// the commit carry the actual content; this is just a navigational hint
+// for `git log` readers.
+//
+// Layout:
+//   <line 1: blank for paragraph break between subject and body>
+//   Captured runs (last <window> per tool):
+//     <tool-a>:
+//       <ts> <status> [<extra>]
+//       ...
+//     <tool-b>:
+//       <ts> <status> [<extra>]
+//
+//   Tools surveyed: <comma-separated list>
+export async function composeBody({ repoRoot, perToolWindow = 3, now = () => new Date(), extraParents = [] }) {
+  const tools = await discoverToolRunsLogs(repoRoot, { extraParents });
+  if (tools.length === 0) {
+    return '(no tool runs.jsonl found to summarise)';
+  }
+  const sections = [];
+  const summarised = [];
+  for (const t of tools) {
+    const records = await tailJsonl(t.path, perToolWindow);
+    if (records.length === 0) {
+      // Skip tools whose log exists but is empty.
+      continue;
+    }
+    summarised.push(t.tool);
+    const lines = [`${t.tool}:`];
+    for (const r of records) {
+      const ts = r.ts || '(no-ts)';
+      const status = r.status || `exit=${r.exitCode ?? '?'}`;
+      const extras = [];
+      if (typeof r.stagingCount === 'number') extras.push(`stagingCount=${r.stagingCount}`);
+      if (typeof r.files === 'number') extras.push(`files=${r.files}`);
+      if (typeof r.entriesTotal === 'number') extras.push(`entries=${r.entriesTotal}`);
+      const extraStr = extras.length ? ` (${extras.join(', ')})` : '';
+      lines.push(`  ${ts} ${status}${extraStr}`);
+    }
+    sections.push(lines.join('\n'));
+  }
+  if (sections.length === 0) {
+    return '(no tool runs.jsonl entries to summarise)';
+  }
+  const header = `Captured runs (last ${perToolWindow} per tool):`;
+  const footer = `Tools surveyed: ${summarised.join(', ')}`;
+  return [header, '', sections.join('\n\n'), '', footer].join('\n');
+}

package/dist/engineering-pa-core/README.md

@@ -0,0 +1,60 @@
+# @stravica-ai/engineering-pa-core
+
+Identity: `@stravica-ai/engineering-pa-core` — the type-agnostic platform spine. PA-type-agnostic engine code that every PA type (engineering, future types) sits on top of.
+
+## Status
+
+**Skeleton — v0.1.0.** Workspace-internal, `"private": true`, not individually published. The single bundled publish is `@stravica-ai/digital-operator-pa`.
+
+Phase 1 Task 4 ports the following from the predecessor `Stravica/dave` `core/` tree:
+
+- `desk` CLI + work-item/project/spawn-log schemas
+- Briefing-contract framework + standards docs
+- Canonical roles (librarian, tool-developer, system-admin, agent-ops)
+- Knowledge retrieval + distillation engine
+- Scheduler primitives
+- Memory-sync mechanism
+- Identity framework + agent terminology docs
+
+Some scope boundaries between `core/`, `cli/`, and `workspace/` are still under discussion (e.g. is the secrets CLI under `core/cli/` or top-level `cli/`?). Task 3 (core inventory) produces the per-file allocation map.
+
+## Layout
+
+```
+packages/core/
+  index.mjs            # placeholder export; populated in Task 4
+  package.json         # name, version, scripts (no deps)
+  README.md            # this file — the contract
+  knowledge/           # methodology-aligned slot for the team-library content
+    README.md          # one-pager pointing at the knowledge-system standard
+    schema/            # librarian-config — distillation rules, taxonomy, weights
+    raw/               # intake — PA-writable observations (per-PA subfolders)
+    canonical/         # wiki — librarian-only writes (curated, conflict-annotated)
+  test/
+    index.test.mjs     # node:test; trivial-but-real coverage
+```
+
+## Tests
+
+```bash
+pnpm --filter @stravica-ai/engineering-pa-core test
+```
+
+## Knowledge subtree
+
+`knowledge/` follows the layer separation from [knowledge-system.md](https://github.com/Stravica/dave/blob/main/operator/knowledge/engineering/standards/knowledge-system.md):
+
+- **`raw/`** — intake. PA-writable subfolders (`raw/{paName}/...`). Append-only.
+- **`canonical/`** — wiki. Librarian-only write. Curated, deduplicated, conflict-annotated.
+- **`schema/`** — librarian configuration. Distillation rules, taxonomy, retrieval weights, half-lives, importance tiers.
+
+v0.1.0 ships the directory shape only. Phase 3 lands the actual team library and the deployed librarian service.
+
+## Standards
+
+This package follows the [tooling standard](../../CONTRIBUTING.md#standards):
+
+- JS only — `.mjs`, `type: module`.
+- Zero runtime npm dependencies.
+- `node:test` for tests.
+- camelCase JSON.

package/dist/engineering-pa-core/bin/desk

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { run } from '../src/desk/cli.mjs';
+run(process.argv.slice(2)).then(
+  (code) => process.exit(code ?? 0),
+  (err) => {
+    console.error(`desk: ${err.message || err}`);
+    process.exit(2);
+  },
+);

package/dist/engineering-pa-core/bin/distill

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../src/distill/cli.mjs').then((m) => m.main(process.argv.slice(2)));

package/dist/engineering-pa-core/bin/memory-sync

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../src/memory-sync/cli.mjs').then((m) => m.main(process.argv.slice(2)));

package/dist/engineering-pa-core/bin/slice

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../src/slice/cli.mjs').then((m) => m.main(process.argv.slice(2)));

package/dist/engineering-pa-core/docs/autonomy-envelope-tracker.md

@@ -0,0 +1,111 @@
+# Autonomy envelope tracker
+
+The per-agent per-task-type approval-state record. Referenced from every operator's CLAUDE.md framing block.
+
+## The mechanism
+
+Each PA agent maintains an autonomy envelope at `agents/<paName>/autonomy-envelope.md`. The file is a markdown document with a YAML frontmatter block carrying the machine-readable state and a body that renders the state for human consumption plus a per-task-type history log.
+
+The envelope is the durable record of what the operator has approved the PA to do without asking, on a per-task-type basis. The PA's day-to-day judgement calibrates from operator reactions; the envelope is the persistent state you check when the reflex is unclear.
+
+## The three states
+
+| State | Meaning | PA behaviour |
+|---|---|---|
+| `fullyApproved` | Operator has said "just do this class of task; don't ask." | Act. Don't ask. If the reflex is to check, resist — the envelope is telling you not to. |
+| `checkBeforeCommitting` | Operator wants sign-off on the durable action but not on the drafting. | Draft, get sign-off before commit / push / publish / ship. Read-only exploration is fine without asking. |
+| `needsFullSupervision` | Operator hasn't approved this class yet, or has explicitly demoted it. | Do not act. Escalate every step. |
+
+The envelope's authority is above the PA's own inclination. If the envelope says a category is `needsFullSupervision` but the PA thinks the operator would be fine with autonomous action, the PA does NOT act — the operator can promote the category via `pa autonomy set` when they're ready.
+
+## Task-type taxonomy
+
+**Core does not enforce a specific task-type taxonomy** — every operator's surface types are different. An example taxonomy the operator might seed with:
+
+- `li-comment-draft` — drafting a LinkedIn comment reply.
+- `li-post-draft` — drafting a full LinkedIn post.
+- `article-draft` — drafting a long-form article.
+- `code-dispatch` — dispatching a code implementer.
+- `code-inline` — writing code in the main thread.
+- `git-commit-push` — committing and pushing.
+- `secret-access` — reading operator secrets from the vault.
+- `contact-outreach` — reaching out to a contact on the operator's behalf.
+
+The operator seeds their own taxonomy per their surface types. The schema (`packages/core/schema/autonomy-envelope.schema.json`) enforces field shape but not the specific set of `taskTypes.id` values.
+
+## CLI
+
+`pa autonomy` — four subcommands.
+
+| Subcommand | Purpose |
+|---|---|
+| `pa autonomy init <agent>` | Create an empty envelope for a new agent. Idempotent — errors if envelope already exists. |
+| `pa autonomy get <agent> [<task-type>]` | Print current state. Task-type optional (prints full table if omitted). |
+| `pa autonomy set <agent> <task-type> <state> [--note <text>]` | Update state. Adds timestamped history entry to the body. Validates state against the enum. |
+| `pa autonomy list [<agent>]` | List envelopes across all agents (or one), with staleness signals (envelope untouched for >30 days → warning). |
+
+Exit codes:
+- `0` ok
+- `1` usage error
+- `2` invalid state or unknown agent
+- `3` IO error
+
+## Session-boot integration
+
+The PA reads the autonomy envelope on every session boot (per CLAUDE.md.template Startup routine). The envelope is one of the small set of files loaded before the first user response.
+
+**Injection surface (per OQ-A1).** The core ships the read-side of the mechanism (schema + CLI + docs); the core does not ship a `SessionStart` hook. Operator-side hook infrastructure (e.g. an operator's `boot-context` tool) can invoke `pa autonomy get <agent> --format json` at session boot and inject the resulting summary into `additionalContext` alongside other live-state blocks.
+
+The `pa autonomy get <agent> --format json` output is stable JSON that a boot-context tool can consume without parsing the markdown file directly.
+
+## Difference from the three-zone role envelope standard
+
+**Related but separate.** The three-zone ROLE envelope is a standard for how ROLES calibrate autonomy across their whole surface — informational, decision-support, decision-authority. That's a property of the role definition.
+
+This tracker is a PER-AGENT, PER-TASK-TYPE record that the operator sets and demotes/promotes dynamically. Different granularity, different lifecycle. Both patterns coexist.
+
+## File shape
+
+Example `agents/<paName>/autonomy-envelope.md`:
+
+```markdown
+---
+agent: dave
+owner: barry
+updated: 2026-07-05T14:30:00Z
+taskTypes:
+  - id: li-comment-draft
+    label: LinkedIn comment draft
+    state: checkBeforeCommitting
+    stateSince: 2026-07-04T09:00:00Z
+    operatorNote: Voice restarts are cheap mid-draft; post-publication corrections are expensive.
+  - id: code-dispatch
+    label: Code implementation dispatch
+    state: fullyApproved
+    stateSince: 2026-07-05T14:30:00Z
+---
+
+# Autonomy envelope — dave
+
+## Current state
+
+| Task type | State | Since | Note |
+|---|---|---|---|
+| LinkedIn comment draft | checkBeforeCommitting | 2026-07-04 | Voice restarts are cheap mid-draft. |
+| Code implementation dispatch | fullyApproved | 2026-07-05 | — |
+
+## History
+
+### 2026-07-05T14:30:00Z — code-dispatch promoted to fullyApproved
+Operator note: none.
+
+### 2026-07-04T09:00:00Z — li-comment-draft demoted to checkBeforeCommitting
+Operator note: Voice restarts are cheap mid-draft; post-publication corrections are expensive.
+```
+
+## Related
+
+- `packages/core/schema/autonomy-envelope.schema.json` — canonical schema.
+- CLAUDE.md.template framing block — the operator-facing pointer.
+- `packages/core/knowledge/operator-interface/escalation-and-correction.md` — how the envelope interacts with escalation.
+- `packages/cli/src/autonomy/` — CLI implementation.

package/dist/engineering-pa-core/docs/blueprints/README.md

@@ -0,0 +1,45 @@
+# Blueprints
+
+Blueprints are step-by-step guides for extending Dave. They cover common setup tasks, integrations, and infrastructure patterns that your PA can follow to configure your environment.
+
+
+## Two tiers
+
+### Blueprints (in named directories)
+
+Proven, tested, ready to follow. Each blueprint directory contains a `blueprint.md` with clear prerequisites, steps, and verification instructions.
+
+- **scheduled-distillation** -- Set up automated knowledge distillation on a cron schedule
+- **tool-integration** -- Connect external tools via MCP servers (GitHub, Slack, Jira, etc.)
+- **git-identity** -- Give your PA its own SSH key and git identity for clean audit trails
+- **docker-services** -- Run a local Docker services cluster (PostgreSQL, Redis, etc.)
+
+### Ideas (in `ideas/`)
+
+Concepts that have not been fleshed out into full blueprints yet. Each is a short description of the idea and what it would involve. If you want to turn an idea into a blueprint, start by creating a directory and writing a `blueprint.md`.
+
+- **work-personal-separation** -- Separating work and personal knowledge domains
+- **knowledge-domain-patterns** -- Common domain structures (recipes, project notes, meeting notes)
+- **office-integration** -- Calendar, email, and document integrations
+- **team-scaling** -- Running multiple PA instances for a team
+- **custom-workspace-views** -- Building custom dashboard pages
+
+
+## How to use
+
+1. Browse the blueprints above or in the workspace UI
+2. Read the `blueprint.md` in the directory you want
+3. Follow the steps -- your PA can help execute them
+4. Adapt the examples to your specific environment
+
+
+## How to contribute
+
+1. Create a new directory under `core/blueprints/`
+2. Write a `blueprint.md` with clear sections: what it does, prerequisites, steps, verification
+3. Keep steps concrete and copy-pasteable where possible
+4. Test the steps on a clean setup before marking it as proven
+
+Custom blueprints can also go in `operator/extensions/blueprints/`. The PA checks extension blueprints before core blueprints, so you can override or extend any core blueprint.
+
+See `CONTRIBUTING.md` for guidelines on contributing blueprints back to the project.

package/dist/engineering-pa-core/docs/blueprints/docker-services/blueprint.md

@@ -0,0 +1,168 @@
+# Docker Services
+
+Set up a local Docker services cluster for your PA to use. Common services include PostgreSQL, Redis, and other infrastructure your projects depend on.
+
+
+## What it does
+
+Creates a Docker Compose configuration that runs local service containers, accessible to your PA and your applications. Services are isolated, reproducible, and easy to tear down.
+
+
+## Prerequisites
+
+- Docker Desktop (macOS/Windows) or Docker Engine (Linux)
+- Docker Compose v2 (usually included with Docker Desktop)
+- Sufficient disk space for container images
+
+
+## Steps
+
+### 1. Create the compose file
+
+Create `docker/docker-compose.yml` in your repo root:
+
+```yaml
+version: "3.8"
+
+services:
+  postgres:
+    image: postgres:16-alpine
+    container_name: dave-postgres
+    environment:
+      POSTGRES_USER: dave
+      POSTGRES_PASSWORD: localdev
+      POSTGRES_DB: dave
+    ports:
+      - "5432:5432"
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U dave"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+  redis:
+    image: redis:7-alpine
+    container_name: dave-redis
+    ports:
+      - "6379:6379"
+    volumes:
+      - redisdata:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+volumes:
+  pgdata:
+  redisdata:
+```
+
+### 2. Start the services
+
+```bash
+cd docker
+docker compose up -d
+```
+
+Verify they are running:
+
+```bash
+docker compose ps
+```
+
+You should see both containers with status "healthy".
+
+### 3. Test connectivity
+
+PostgreSQL:
+
+```bash
+docker exec -it dave-postgres psql -U dave -c "SELECT version();"
+```
+
+Redis:
+
+```bash
+docker exec -it dave-redis redis-cli ping
+# Should output: PONG
+```
+
+### 4. Store credentials in the vault
+
+```bash
+node core/tools/secrets/bin/secrets set POSTGRES_URL "postgresql://dave:localdev@localhost:5432/dave"
+node core/tools/secrets/bin/secrets set REDIS_URL "redis://localhost:6379"
+```
+
+### 5. Configure your PA to use the services
+
+Your PA can now reference these services by their connection URLs. When your PA needs database access for a project, it will use the credentials from the vault.
+
+
+## Managing services
+
+Start all services:
+
+```bash
+cd docker && docker compose up -d
+```
+
+Stop all services (preserves data):
+
+```bash
+cd docker && docker compose stop
+```
+
+Remove all services and data:
+
+```bash
+cd docker && docker compose down -v
+```
+
+View logs:
+
+```bash
+cd docker && docker compose logs -f
+```
+
+
+## Adding more services
+
+Add new service blocks to `docker-compose.yml`. Common additions:
+
+**Elasticsearch:**
+```yaml
+  elasticsearch:
+    image: elasticsearch:8.12.0
+    container_name: dave-elasticsearch
+    environment:
+      - discovery.type=single-node
+      - xpack.security.enabled=false
+    ports:
+      - "9200:9200"
+```
+
+**MinIO (S3-compatible storage):**
+```yaml
+  minio:
+    image: minio/minio
+    container_name: dave-minio
+    command: server /data --console-address ":9001"
+    environment:
+      MINIO_ROOT_USER: minioadmin
+      MINIO_ROOT_PASSWORD: minioadmin
+    ports:
+      - "9000:9000"
+      - "9001:9001"
+```
+
+
+## Notes
+
+- Default credentials are for local development only -- never use them in production
+- Named volumes (`pgdata`, `redisdata`) persist data across container restarts
+- Use `docker compose down -v` to completely reset all data
+- Port conflicts: if a port is already in use, change the host port mapping (e.g. `5433:5432`)

package/dist/engineering-pa-core/docs/blueprints/git-identity/blueprint.md

@@ -0,0 +1,116 @@
+# Git Identity
+
+Give your PA its own dedicated git identity with a separate SSH key and commit author. This creates a clear audit trail -- you can always tell which commits were made by you and which by your PA.
+
+
+## What it does
+
+Sets up:
+- A dedicated SSH keypair for the PA
+- Git author configuration (name and email)
+- GitHub deploy key or user association
+- Local `.gitconfig` scoping so the PA uses its own identity automatically
+
+
+## Prerequisites
+
+- Git installed
+- SSH client installed
+- A GitHub account (or other git hosting) where you want the PA to push
+- Access to add SSH keys to your git hosting provider
+
+
+## Steps
+
+### 1. Generate an SSH keypair
+
+Create a dedicated key for your PA. Replace `dave` with your PA's name:
+
+```bash
+ssh-keygen -t ed25519 -C "dave-pa@yourdomain.com" -f ~/.ssh/dave_pa_ed25519 -N ""
+```
+
+This creates:
+- `~/.ssh/dave_pa_ed25519` (private key)
+- `~/.ssh/dave_pa_ed25519.pub` (public key)
+
+### 2. Add the public key to GitHub
+
+Copy the public key:
+
+```bash
+cat ~/.ssh/dave_pa_ed25519.pub
+```
+
+Then add it to GitHub:
+- Go to GitHub Settings > SSH and GPG keys > New SSH key
+- Title: "Dave PA" (or your PA's name)
+- Key type: Authentication key
+- Paste the public key
+
+Alternatively, add it as a deploy key on specific repositories if you want to limit access.
+
+### 3. Configure SSH to use the PA key
+
+Add a host alias to `~/.ssh/config`:
+
+```
+Host github-pa
+  HostName github.com
+  User git
+  IdentityFile ~/.ssh/dave_pa_ed25519
+  IdentitiesOnly yes
+```
+
+### 4. Configure git identity
+
+Set up the PA's git identity in your repo. Create or edit `.gitconfig` in your repo root:
+
+```ini
+[user]
+    name = Dave (PA)
+    email = dave-pa@yourdomain.com
+```
+
+Then tell git to use this config for this repo:
+
+```bash
+git config --local include.path ../.gitconfig
+```
+
+Alternatively, set it directly:
+
+```bash
+git config --local user.name "Dave (PA)"
+git config --local user.email "dave-pa@yourdomain.com"
+```
+
+### 5. Update remote URL (optional)
+
+If you want the PA to push using its own SSH key, update the remote to use the host alias:
+
+```bash
+git remote set-url origin git@github-pa:yourusername/yourrepo.git
+```
+
+### 6. Verify
+
+Test that the PA's identity works:
+
+```bash
+ssh -T github-pa
+# Should output: Hi yourusername! You've successfully authenticated...
+
+git log --oneline -1
+# Commits should show "Dave (PA)" as author
+```
+
+
+## Security notes
+
+- The PA's SSH key should have the minimum required access -- prefer deploy keys over personal access
+- Never share the private key or commit it to the repository
+- Store the private key path in your secrets vault for reference
+- If the PA only needs to push to specific repos, use per-repo deploy keys instead of a global SSH key
+- Consider enabling signed commits for the PA identity for additional verification
+- Periodically rotate the SSH key, especially if the PA operates on shared infrastructure

package/dist/engineering-pa-core/docs/blueprints/ideas/custom-workspace-views.md

@@ -0,0 +1,9 @@
+# Custom Workspace Views
+
+Build custom dashboard pages for the workspace server that display project-specific or domain-specific information.
+
+The workspace server already supports serving HTML from the app directory. Custom views would be additional HTML pages that fetch data from the API and present it in specialised formats -- a sprint board view, a knowledge graph visualisation, a timeline of decisions, or a metrics dashboard.
+
+Implementation approach: create new HTML files in `core/tools/workspace/app/` or `operator/extensions/workspace/` that follow the same design system (dark theme, monospace font, inline CSS). The workspace shell would detect custom pages and add them to the navigation automatically.
+
+Example views: a "sprint board" that groups work items into columns with drag-and-drop, a "knowledge map" showing domain connections as a graph, a "decision log" that aggregates ADRs across projects with search, or a "health check" page showing system status (git sync, scheduled tasks, vault status).