dev-cockpit 0.1.0

package/dist/watchers/types.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Watcher subsystem types.
+ *
+ * The watcher manager works on a *normalized* repo config — a per-repo
+ * declaration that says where the repo lives, which paths trigger work,
+ * and what commands to run. Profiles produce these from their own config
+ * shapes before constructing a WatcherManager.
+ */
+export interface NormalizedRepoConfig {
+    name: string;
+    /** Glob patterns (chokidar shape) — paths that should trigger watcher / lint. */
+    discover: string[];
+    /** Shell command spawned as the persistent watcher (or undefined for none). */
+    watch: string | undefined;
+    /** Per-extension lint commands. Undefined = no lint for that family. */
+    lint: {
+        js: string | undefined;
+        css: string | undefined;
+        php: string | undefined;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/watchers/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/watchers/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,iFAAiF;IACjF,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,+EAA+E;IAC/E,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,wEAAwE;IACxE,IAAI,EAAE;QACJ,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC;QACvB,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;QACxB,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;KACzB,CAAC;CACH"}

package/dist/watchers/types.js

@@ -0,0 +1,9 @@
+/**
+ * Watcher subsystem types.
+ *
+ * The watcher manager works on a *normalized* repo config — a per-repo
+ * declaration that says where the repo lives, which paths trigger work,
+ * and what commands to run. Profiles produce these from their own config
+ * shapes before constructing a WatcherManager.
+ */
+export {};

package/docs/commands.md

@@ -0,0 +1,71 @@
+# Commands
+
+`dev-cockpit` ships four core commands. A profile contributes its own commands via `setupCli(program)` — these register **first**, so a profile can take over a core command name (the matching core command is then skipped).
+
+| Command       | What it does                                                                  |
+|---------------|-------------------------------------------------------------------------------|
+| `dev`         | Boots the three-pane TUI (Repos / Output / Health / Help).                    |
+| `doctor`      | Runs every registered health check once and prints a status table.            |
+| `init-config` | Writes a starter `cockpit.yaml` in the current directory.                     |
+| `mount`       | Generates a Docker compose overlay for declared bind mounts.                  |
+
+## `dev`
+
+```
+dev-cockpit dev [-c <path>]
+```
+
+Loads `cockpit.yaml`, wires the active profile + config-declared health checks into the cockpit shell, and starts an optional Docker log tailer if the config declares services to tail.
+
+## `doctor`
+
+```
+dev-cockpit doctor [-c <path>]
+```
+
+Builds the health registry from `config.health[]` plus `profile.healthChecks`, runs the `startup` trigger set once, and prints `✓ / ⚠ / ✗` per check. Exits non-zero on any `error` severity.
+
+## `init-config`
+
+```
+dev-cockpit init-config [--with-docker] [-f|--force]
+```
+
+Writes a `cockpit.yaml` template at the current directory. `--with-docker` uncomments the docker block. The template is otherwise heavily commented — uncomment the sections you need.
+
+## `mount`
+
+```
+dev-cockpit mount [-c <path>] [-s|--service <name>]
+dev-cockpit mount status [-c <path>]
+dev-cockpit mount clear [-c <path>]
+```
+
+Merges `config.mounts[]` with `profile.mountCandidatesProvider?.()`, then writes:
+
+- `<workspace>/docker-compose.dev-cockpit.yml` — the overlay
+- `<state-dir>/mount.manifest.json` — what was applied + when
+
+See [mount.md](./mount.md) for the full mount story.
+
+## Profile setupCli
+
+A profile bundle implements the `Profile` type's `setupCli(program)` to register additional commands or override core ones:
+
+```ts
+import type { Profile } from 'dev-cockpit';
+
+export const myProfile: Profile = {
+  appName: 'my-app',
+  setupCli(program) {
+    program
+      .command('release')
+      .description('cut a release')
+      .action(async () => {
+        /* … */
+      });
+  },
+};
+```
+
+The profile is invoked **before** the core commands register. Any name the profile claims (`dev`, `doctor`, etc.) silently skips its core counterpart — no overrides API, no array mutation, just registration order.

package/docs/config-reference.md

@@ -0,0 +1,20 @@
+# Config reference
+
+A `cockpit.yaml` lives at the root of your project. The cockpit reads it on startup and seeds the store from it.
+
+## Top-level keys
+
+- `version` (number, required) — schema version. Must match the running build's `CONFIG_VERSION`.
+- `appName` (string, required) — used as the state-dir name (`~/.local/state/<appName>/...`) and the OS-notification title prefix.
+- `watchers` (array) — see watchers.md.
+- `repos` (array) — items to show in the Repos pane.
+- `docker` (object) — `composeFile` + `services[]`. Omit the whole block on plain-Node projects.
+- `highlights` (array) — patterns applied to all log streams.
+- `health` (array) — see health.md.
+- `help` (object) — extra docs sources + `defaultPage`.
+- `notifications` (object) — see notifications.md.
+- `profile` (object) — namespace for profile-specific extension keys (e.g. `profile.myapp = { ... }`). Each profile validates its own block via its `configSchemaExt`.
+
+## Example
+
+A fully-commented example lives at `examples/cockpit.yaml` in the dev-cockpit package. Copy it as a starting point and trim what doesn't apply.

package/docs/getting-started.md

@@ -0,0 +1,39 @@
+# Getting started
+
+Run `dev-cockpit dev` from a directory that contains a `cockpit.yaml`. The TUI boots into the **Repos** tab and starts any watchers + health checks declared in your config.
+
+## At a glance
+
+- **Cycle tabs** — `←` / `→` (or `Tab` / `Shift-Tab`)
+- **Quit** — `q`
+- **Toggle notifications for this session** — `n`
+
+Every tab fills the full terminal. Modals (filter, search) render in place of the active pane.
+
+## What the panes do
+
+- **Repos** — list of repos and (optionally) Docker services with watcher / lint status; per-row actions live here.
+- **Output** — streaming logs from watchers and Docker services, with filter and search modals.
+- **Health** — workspace health checks; each check has a one-keystroke remediation.
+- **Help** — this guide. `j` / `k` to flip pages, `↑` / `↓` to scroll.
+
+## Try it on a fixture
+
+The repo ships two minimal sample projects under `tests/fixtures/`:
+
+- `tests/fixtures/plain-node/` — no docker dependency. Watcher (`tsc --watch`), `http-ok` health against a tiny http server, and a `file-exists` health on `package-lock.json`.
+- `tests/fixtures/dockerized/` — a `docker compose` stack (alpine heartbeat + redis), `container-running` and `port-open` health checks, log tailing.
+
+```sh
+cd tests/fixtures/plain-node
+npm install
+node src/server.mjs &      # so the http-ok check goes green
+dev-cockpit dev
+
+# Or for the docker variant:
+cd tests/fixtures/dockerized
+docker compose up -d
+dev-cockpit dev
+```
+
+These fixtures double as the project's smoke tests (`tests/fixtures/smoke.test.ts`) — running `npm test` parses each `cockpit.yaml` and asserts the shell renders.

package/docs/health.md

@@ -0,0 +1,120 @@
+# Health
+
+A health check is a small predicate that decides whether something in your workspace is `ok`, `warn`, or `error`. Each check pairs with a one-keystroke remediation that the user can press from the Health pane to fix it.
+
+The cockpit re-runs health checks on three triggers:
+
+| Trigger    | When                                                                  |
+|------------|-----------------------------------------------------------------------|
+| `startup`  | once, at boot                                                         |
+| `fsevent`  | when the watcher reports a file change (debounced ~500 ms)            |
+| `lockfile` | when `composer.lock`, `package-lock.json`, or `yarn.lock` changes     |
+| `docker`   | when a docker event is signalled (e.g. by the docker subsystem)       |
+
+Transitions (`ok → error`, `error → ok`) fire OS notifications according to the global `notifications:` block, optionally overridden per-check.
+
+## Built-in check vocabulary
+
+| Type                | Required args        | Optional args                | Default triggers          |
+|---------------------|----------------------|------------------------------|---------------------------|
+| `container-running` | `container`          |                              | `startup`, `docker`       |
+| `port-open`         | `port` (number)      | `host` (default `127.0.0.1`) | `startup`                 |
+| `http-ok`           | `url`                | `expectStatus` (default 200) | `startup`                 |
+| `file-exists`       | `path`               |                              | `startup`, `fsevent`      |
+| `exec-zero`         | `command`            | `args[]`, `cwd`              | `startup`                 |
+
+Defaults can be overridden by setting `triggers:` and `severity:` on the entry.
+
+## Config shape
+
+```yaml
+health:
+  - id: api-up
+    label: API responds
+    type: http-ok
+    url: http://localhost:3000/health
+    expectStatus: 200
+    remediation:
+      key: A
+      label: restart api
+      command: docker compose restart api
+
+  - id: db-up
+    label: DB reachable
+    type: port-open
+    port: 5432
+    triggers: [startup]
+    remediation:
+      key: D
+      label: start db
+      command: docker compose up -d db
+    notify:
+      onTransitionTo: [health-failed]   # only notify on going-down
+```
+
+## Remediations
+
+Each health entry declares one remediation. It can be either:
+
+- **Declarative shell command** — `command: "npm install"` (with optional `cwd`). Stdout/stderr stream to the Output pane tagged `health:<id>`.
+- **Programmatic function** — only available to checks contributed by a profile (TypeScript code), via `run(ctx, workspaceRoot)`.
+
+The remediation `key` is a single uppercase letter. Pressing the key (lowercase or upper) on the Health pane runs the remediation; the row shows `… (running…)` until completion, with a minimum 1.5 s banner hold so fast-finishing actions stay visible.
+
+## Notification policy
+
+Per-check `notify:` overrides:
+
+| Setting                                       | Effect                                                |
+|-----------------------------------------------|-------------------------------------------------------|
+| omitted                                       | inherit global `notifications:` policy                |
+| `notify: false`                               | always silent for this check                          |
+| `notify: { onTransitionTo: [health-failed] }` | only notify on the listed transition events           |
+
+The session toggle (`n` keystroke) and global `notifications.enabled: false` always silence everything — per-check overrides cannot opt back in.
+
+## Profile-contributed checks
+
+A profile bundles pre-built checks (TypeScript with closures over project-specific helpers) via `Profile.healthChecks`. They register **after** config-driven entries and may use any custom `type` id. **Built-in `type` ids cannot be overridden** by profile checks — the registry rejects them with a warning, so the built-in vocabulary stays predictable.
+
+```ts
+import type { Profile } from 'dev-cockpit';
+
+export const myProfile: Profile = {
+  appName: 'my-cockpit',
+  healthChecks: [
+    {
+      id: 'composer-installed',
+      label: 'Composer',
+      severity: 'error',
+      triggers: ['startup', 'lockfile'],
+      predicate: async (ctx) => { /* … */ },
+      remediation: { key: 'R', label: 'composer install', run: async (ctx, root) => { /* … */ } },
+    },
+  ],
+};
+```
+
+## Wiring
+
+In your `dev` command, pass `health: { … }` to `runCockpit`:
+
+```ts
+import { runCockpit, buildHealthContext } from 'dev-cockpit';
+
+await runCockpit({
+  profile: myProfile,
+  footerLegends: { /* … */ },
+  health: {
+    workspaceRoot,
+    profileChecks: myProfile.healthChecks,
+    configEntries: config.health,
+    ctx: buildHealthContext(workspaceRoot, appendOutput),
+    notifications: config.notifications,
+    appName: 'my-cockpit',
+    subscribeFsEvents: (listener) => watcherManager.subscribeFsEvents(listener),
+  },
+}).waitUntilExit();
+```
+
+`useHealth` (called internally by `<Cockpit>`) owns the scheduler lifecycle, transition diffing, notification dispatch, and remediation routing. Consumers do not instantiate `HealthScheduler` directly.

package/docs/index.md

@@ -0,0 +1,13 @@
+# dev-cockpit help
+
+This is the in-cockpit Help tab. The pages below explain what each pane does, how to drive the cockpit from the keyboard, and how to configure it for your project.
+
+- [Getting started](./getting-started.md) — first run and what to expect
+- [Panes](./panes.md) — Repos, Output, Health, Help
+- [Watchers](./watchers.md) — long-running commands streamed into Output
+- [Health](./health.md) — checks and one-keystroke remediations
+- [Commands](./commands.md) — the four core CLI commands + profile `setupCli`
+- [init-config](./init-config.md) — scaffold a starter `cockpit.yaml`
+- [Mount](./mount.md) — host ↔ container bind-mount overlay
+- [Notifications](./notifications.md) — transition-only OS notifications
+- [Config reference](./config-reference.md) — `cockpit.yaml` schema

package/docs/init-config.md

@@ -0,0 +1,46 @@
+# init-config
+
+`dev-cockpit init-config` writes a starter `cockpit.yaml` at the current working directory. Two modes:
+
+```
+dev-cockpit init-config [--with-docker] [-f|--force]      # static template
+dev-cockpit init-config -i [-f|--force]                    # interactive wizard
+```
+
+## Flags
+
+| Flag                 | Default | Effect                                                                                        |
+|----------------------|---------|-----------------------------------------------------------------------------------------------|
+| `-i, --interactive`  | off     | Walk through prompts to populate the file. Skips the static template.                         |
+| `--with-docker`      | off     | Uncomments the `docker:` block in the static template (ignored in `--interactive` mode).      |
+| `-f, --force`        | off     | Overwrites an existing `cockpit.yaml` instead of refusing.                                    |
+
+## Static template
+
+`version: 1` and `appName` are required and uncommented. Everything else (watchers, repos, docker, highlights, health, help, notifications, mounts) ships as a commented example. You uncomment what you need. Best when you already know what you want — fastest path from scratch to "edit me".
+
+## Interactive wizard
+
+The recommended path the first time you set the cockpit up on a project. It walks through seven steps, with project sniffing pre-populating sensible defaults so you usually just press enter:
+
+| Step | Section | What it asks + auto-detects |
+|------|---------|------------------------------|
+| 1 | **App name** | Defaults to `package.json` `name`, then the cwd basename. |
+| 2 | **Docker** | Detects `compose.yaml` / `docker-compose.yml` and parses its services. Offers them as a multi-select. Skip entirely for non-compose projects. |
+| 3 | **Watchers** | Surfaces `package.json` scripts (`dev`, `watch`, `start`, `serve`) as pre-checked candidates. Anything that runs forever and writes to stdout — `vite`, `tsc --watch`, `php artisan serve`, `tail -f storage/logs/laravel.log` — fits here. |
+| 4 | **Repos** | Detects npm/yarn/pnpm workspaces; falls back to a single `.` entry. Each entry becomes a row in the Repos pane (with `r/w/l` keystroke actions when a profile bundle wires them). |
+| 5 | **Highlights** | Regex patterns that re-colour matching Output lines. `error`-severity matches additionally feed the Recent Errors strip + OS notifications. |
+| 6 | **Health** | Reframed as test-and-fix pairs. Pick one of the five built-in types (`container-running`, `port-open`, `http-ok`, `file-exists`, `exec-zero`), supply the type-specific arg(s), then bind a single-keystroke remediation. Add as many checks as you like — same type repeats freely (e.g. `port-open` for 5432, 6379, 8108). `container-running` is hidden when no docker block was declared. |
+| 7 | **Notifications** | Toggle native OS notifications on state transitions. |
+
+After writing the file, the wizard offers to run `dev-cockpit doctor` immediately so you get instant feedback that the config parses + each declared health check has a baseline state.
+
+The wizard scaffolds a *working* config. Anything more advanced (custom triggers, `expectStatus`, exec args, mounts, profile namespaces) is a hand-edit on the generated file.
+
+## Profile-driven defaults
+
+When a profile is active (e.g. `<profile-bin> init-config -i`), the wizard defaults `appName` to the profile's. Profile bundles can also register their own `init-config` via `setupCli(program)` if they want a domain-specific template — the generic command is skipped when the profile claims the slot.
+
+## Schema reference
+
+The full schema definition lives at [config-reference.md](./config-reference.md).

package/docs/mount.md

@@ -0,0 +1,55 @@
+# Mount
+
+`dev-cockpit mount` generates a Docker compose overlay describing host ↔ container bind mounts so you can swap a containerised dependency for a local checkout.
+
+## When to use it
+
+When you're developing a containerised app and want changes in a local checkout to flow live into the running container — e.g. mount your local `./packages/api` into `/srv/api` inside the `web` service.
+
+## Mount sources
+
+Mounts come from two places, merged on `containerPath` (config wins on collision):
+
+1. **`config.mounts[]`** — explicit, declared in `cockpit.yaml`:
+   ```yaml
+   mounts:
+     - hostPath: ./packages/api
+       containerPath: /srv/api
+   ```
+2. **`profile.mountCandidatesProvider?.()`** — discovered programmatically by the active profile (e.g. walking a manifest file to find local checkouts of declared dependencies).
+
+## Output
+
+- `<workspace>/docker-compose.dev-cockpit.yml` — the overlay file. Apply it alongside your existing compose file:
+  ```
+  docker compose -f docker-compose.yml -f docker-compose.dev-cockpit.yml up -d
+  ```
+- `<state-dir>/mount.manifest.json` — records what was applied + when. Used by `mount status` and `mount clear`.
+
+The state dir lives under `XDG_STATE_HOME/<appName>/<workspace-hash>/`.
+
+## Subcommands
+
+```
+dev-cockpit mount [-s|--service <name>]   # write/refresh the overlay
+dev-cockpit mount status                  # print active overlay manifest
+dev-cockpit mount clear                   # delete overlay + manifest
+```
+
+If `--service` is omitted, the first entry in `config.docker.services` is used. Pass `--service` explicitly when your compose file has multiple services and you want mounts attached to a non-default one.
+
+## Profile-side discovery
+
+A profile that scans a manifest (e.g. `composer.json`, `package.json` workspaces) for local checkouts implements `mountCandidatesProvider` and returns `Mount[]`. Discovered candidates blend with `config.mounts[]` automatically:
+
+```ts
+export const myProfile: Profile = {
+  appName: 'my-app',
+  mountCandidatesProvider(): Mount[] {
+    return findLocalCheckouts().map((c) => ({
+      hostPath: c.hostPath,
+      containerPath: c.containerPath,
+    }));
+  },
+};
+```

package/docs/notifications.md

@@ -0,0 +1,39 @@
+# Notifications
+
+OS notifications fire on **state transitions only** — never on every check, never on every log line. The transition detector compares the previous health snapshot to the new one and emits one event per check that crossed the `error` threshold.
+
+## Layered policy
+
+1. **Global default** — `notifications:` block in `cockpit.yaml`:
+
+   ```yaml
+   notifications:
+     enabled: true
+     onTransitionTo:
+       - error
+       - recovered
+   ```
+
+2. **Per-item override** — a `notify:` field on any watcher or health check:
+
+   ```yaml
+   - id: lint
+     command: npx eslint . --watch
+     notify: false                       # mute this item
+
+   - id: api-up
+     type: http-ok
+     url: http://localhost:3000/health
+     notify:
+       onTransitionTo: [error]           # only on going-down, not on recovery
+   ```
+
+3. **Session toggle** — press `n` in the cockpit to mute *all* notifications for the current session (overrides config). The Health pane shows the current session state at the bottom.
+
+## Events
+
+- `health-failed` / `health-recovered` — emitted by the health framework
+- `build-failed` / `build-recovered` — emitted by watchers
+- Profiles can emit their own event names; they flow through the same pipeline.
+
+The `appName` configured in `cockpit.yaml` is used as the title prefix on every notification (e.g. `my-app — API responds`).

package/docs/panes.md

@@ -0,0 +1,45 @@
+# Panes
+
+## Repos
+
+Glyphs:
+
+- ● running (green)
+- ○ idle (gray/dim)
+- ✗ failing (red)
+
+Lint sub-glyph (after the name): ✓ pass · ! fail · (none) unknown.
+
+Selected row is marked with a leading `>` and the pane border is highlighted when this pane has focus.
+
+Actions (when a row is selected):
+
+- `r` — primary action (rebuild for repo entries, restart for Docker entries)
+- `w` — toggle watcher (repo entries only)
+- `l` — run lint (repo entries only)
+
+In-flight actions show a banner at the top of the pane plus an inline `(running…)` next to the active row.
+
+## Output
+
+Streaming source-tagged logs.
+
+- `↑` / `↓` — scroll one line
+- `PgUp` / `PgDn` — scroll one page
+- `Enter` — jump to bottom (auto-scroll resumes)
+- `c` — clear
+- `/` — open Search modal
+- `f` — open Filter modal
+- `e` — open the most recent error with a `file:line` reference in `$EDITOR`
+
+A "Recent errors" strip appears at the top when one or more error lines have been pushed (most-recent first, capped at 3 visible).
+
+## Health
+
+Each row shows: severity glyph, label, remediation key (if any). `Enter` toggles the diagnostic detail for the selected row. Press the remediation letter to fix.
+
+While a remediation runs, a banner appears at the top and the running row shows `…  (running…)`.
+
+## Help
+
+This pane. `j` / `k` (or `Shift-Tab` / `Tab`) cycle pages. `↑` / `↓` scroll. `g` / `G` jump to top / bottom. `←` / `→` always exit Help to the next tab.

package/docs/watchers.md

@@ -0,0 +1,27 @@
+# Watchers
+
+A watcher is a long-running command (typically `tsc --watch`, `vitest --watch`, `eslint --watch`) declared in `cockpit.yaml` under `watchers:`. The cockpit spawns each watcher lazily on first focus and streams its stdout/stderr into the Output pane, prefixed by source id.
+
+## Config shape
+
+```yaml
+watchers:
+  - id: typecheck
+    label: tsc --watch
+    command: npx tsc --watch --noEmit
+    color: cyan
+  - id: test
+    label: vitest
+    command: npx vitest --watch
+    color: magenta
+    notify: false           # mute notifications for this watcher
+    restartOn:
+      - package.json
+      - tsconfig.json
+```
+
+- `id` is required; it appears as the source prefix on every emitted line.
+- `restartOn` lets you re-spawn the watcher when specific files change.
+- `notify` overrides the global notifications policy for this watcher (see notifications.md).
+
+This page is a stub — full watcher behavior is fleshed out in subsequent phases.

package/examples/cockpit.yaml

@@ -0,0 +1,116 @@
+# cockpit.yaml — example config
+# Run `dev-cockpit dev` from the directory containing this file.
+
+version: 1                            # config schema version; required
+appName: my-app                       # state dir: ~/.local/state/my-app/
+
+# Watchers — long-running commands streamed into the Output pane.
+watchers:
+  - id: typecheck
+    label: tsc --watch
+    command: npx tsc --watch --noEmit
+    color: cyan
+  - id: test
+    label: vitest
+    command: npx vitest --watch
+    color: magenta
+  - id: lint
+    label: eslint
+    command: npx eslint . --watch
+    color: yellow
+    notify: false                     # mute notifications for this watcher
+    restartOn:
+      - package.json
+      - .eslintrc.*
+
+# Repos — what shows in the Repos pane (optional; default = empty).
+repos:
+  - id: api
+    path: ./packages/api
+    label: API
+  - id: web
+    path: ./packages/web
+    label: Web
+
+# Docker — enables container log tailing, container health checks, mount overlay.
+# Omit this whole block for plain-Node projects; the docker tab/section won't appear.
+docker:
+  composeFile: ./docker-compose.yml
+  services:
+    - name: web
+      tail: true
+    - name: db
+      tail: true
+    - name: redis
+      tail: false
+
+# Highlight patterns — applied to all log streams.
+highlights:
+  - pattern: ERROR
+    severity: error
+  - pattern: FATAL
+    severity: error
+  - pattern: WARN
+    severity: warn
+  - pattern: "Stack trace"
+    severity: error
+
+# Health checks — `type` references a built-in or profile-registered check id.
+# Each check has a one-keystroke remediation.
+health:
+  - id: api-up
+    label: API responds
+    type: http-ok
+    url: http://localhost:3000/health
+    notify:
+      onTransitionTo: [error]         # only notify on going-down, not on recovery
+    remediation:
+      key: a
+      label: restart api
+      command: docker compose restart web
+
+  - id: db-running
+    label: DB container running
+    type: container-running
+    container: db
+    remediation:
+      key: d
+      label: bring db up
+      command: docker compose up -d db
+
+  - id: env-file
+    label: .env exists
+    type: file-exists
+    path: ./.env
+    remediation:
+      key: e
+      label: copy .env.example
+      command: cp .env.example .env
+
+  - id: migrations
+    label: migrations applied
+    type: exec-zero
+    command: npm run db:check
+    remediation:
+      key: m
+      label: run migrations
+      command: npm run db:migrate
+
+# Help — extra markdown directories layered on top of core's built-in docs.
+help:
+  sources:
+    - ./docs
+  defaultPage: getting-started
+
+# Notifications — fire on state transitions only.
+notifications:
+  enabled: true
+  onTransitionTo:
+    - error
+    - recovered
+
+# Profile-specific config lives under `profile.<name>` — validated by the
+# profile's `configSchemaExt` zod extension. Generic core ignores this block.
+# profile:
+#   myapp:
+#     someKey: value