Phase 0 · 0.A–0.C — monorepo scaffold + strict TS/lint/test spine

.npmrc

@@ -0,0 +1,11 @@
+# pnpm configuration (see docs/tech-stack.md, phase-0-foundations 0.A)
+# Reproducible installs: peers are installed automatically so a fresh checkout resolves
+# the same graph.
+#
+# strict-peer-dependencies is kept OFF for local installs deliberately: from Phase 1 the
+# surface packages pull React / ReactFlow / Tauri / provider SDKs whose required peers are
+# not all in the tree at once, so a hard local `true` would break fresh checkouts. Peer
+# drift is instead caught by a CI-only strict gate (0.G), e.g.
+#   pnpm install --frozen-lockfile --config.strict-peer-dependencies=true
+auto-install-peers=true
+strict-peer-dependencies=false

.nvmrc

@@ -0,0 +1 @@
+22

.prettierignore

@@ -0,0 +1,18 @@
+# Build output, caches, deps
+**/dist/**
+**/.turbo/**
+**/coverage/**
+**/node_modules/**
+
+# Lockfile
+pnpm-lock.yaml
+
+# The docs/ tree is governed by docs/standards/documentation-style.md, not Prettier
+# (and docs/analysis/_archive/* are FROZEN provenance — never reformat them).
+docs/**
+
+# Markdown anywhere else (root README, CLAUDE.md, AGENTS.md, package READMEs).
+**/*.md
+
+# Agent scaffolding (own conventions)
+.claude/**

.prettierrc.json

@@ -0,0 +1,9 @@
+{
+  "semi": true,
+  "singleQuote": true,
+  "trailingComma": "all",
+  "printWidth": 100,
+  "tabWidth": 2,
+  "arrowParens": "always",
+  "endOfLine": "lf"
+}

apps/cli/README.md

@@ -0,0 +1,7 @@
+# `apps/cli` — placeholder
+
+Terminal CLI (`relavium`) — the engine's first real consumer + regression harness.
+
+> **Not built yet.** Directory placeholder; built out in
+> [Phase 2 — CLI](../../docs/roadmap/phases/phase-2-cli.md). No `package.json` yet, so
+> pnpm/Turborepo do not treat it as a workspace.

apps/desktop/README.md

@@ -0,0 +1,8 @@
+# `apps/desktop` — placeholder
+
+Tauri v2 desktop app — the agent-management center (canvas, run monitoring).
+**Not an IDE** ([ADR-0007](../../docs/decisions/0007-desktop-is-not-an-ide.md)).
+
+> **Not built yet.** Directory placeholder; built out in
+> [Phase 3 — desktop](../../docs/roadmap/phases/phase-3-desktop.md). No `package.json`
+> yet, so pnpm/Turborepo do not treat it as a workspace.

apps/vscode-extension/README.md

@@ -0,0 +1,7 @@
+# `apps/vscode-extension` — placeholder
+
+Standalone VS Code extension (bundles the engine in-process).
+
+> **Not built yet.** Directory placeholder; built out in
+> [Phase 4 — VS Code](../../docs/roadmap/phases/phase-4-vscode.md). No `package.json`
+> yet, so pnpm/Turborepo do not treat it as a workspace.

docs/roadmap/current.md

@@ -2,7 +2,7 @@
 
 > Status: Living
 
-> Last updated: 2026-06-03
+> Last updated: 2026-06-04
 
 - **Related**: [README.md](README.md), [phases/phase-0-foundations.md](phases/phase-0-foundations.md), [phases/phase-1-engine-and-llm.md](phases/phase-1-engine-and-llm.md), [../project-structure.md](../project-structure.md), [../tech-stack.md](../tech-stack.md)
 
@@ -13,9 +13,14 @@ actions. The full phase plan and the global milestone spine are in
 
 ## Where we are
 
-**Documentation and design: complete. No code written yet.** The repository
-(`github.com/HodeTech/Relavium`) holds the `docs/` tree only. The foundation is
-settled and recorded:
+**Documentation and design: complete. The monorepo scaffold (Phase 0 workstreams
+0.A–0.C) has landed and is green.** The repository (`github.com/HodeTech/Relavium`)
+now holds the `docs/` tree **plus** the Turborepo + pnpm workspace, the strict
+`tsconfig` bases, the root ESLint/Prettier/Vitest spine, and a buildable
+`@relavium/shared` scaffold — `pnpm install && pnpm turbo run lint typecheck test build`
+is green and `format:check` is clean. The remaining Phase-0 workstreams (0.D/0.E
+schemas, 0.F seam fence, 0.G CI, 0.H docs, 0.I `@relavium/db`) are still open before
+**M0**. The foundation is settled and recorded:
 
 - Product vision, UVP, and hard constraints (desktop is agent-management, not an
   IDE; local-first Product Phase 1; git-native workflow YAML).
@@ -50,9 +55,10 @@ settled and recorded:
 
 ## What is active now
 
-The project is at the **start of build-order step 1: scaffolding the monorepo.**
-This is **[Phase 0 — foundations](phases/phase-0-foundations.md)** (Product Phase 1).
-Phase 0 ships **types and tooling, not features**; its job is to make
+The project is in **build-order step 1: scaffolding the monorepo** — the toolchain
+half (0.A–0.C) is **done and green**, and the next work is the critical-path schemas
+(0.D/0.E). This is **[Phase 0 — foundations](phases/phase-0-foundations.md)** (Product
+Phase 1). Phase 0 ships **types and tooling, not features**; its job is to make
 [Phase 1 — the engine critical path](phases/phase-1-engine-and-llm.md) safe to start
 against a frozen contract and a green CI gate. Until Phase 0's
 [exit criteria](phases/phase-0-foundations.md#exit-criteria-go--no-go) pass, no
@@ -68,6 +74,10 @@ The first workstreams of Phase 0, in order. `0.A → 0.B → 0.C → 0.D` are se
 task lists and acceptance criteria are in
 [phase-0-foundations.md](phases/phase-0-foundations.md#work-breakdown).
 
+> **✅ 0.A / 0.B / 0.C are landed and green** (the monorepo + toolchain spine). The
+> active focus is now **[0.D → 0.E]** — `@relavium/shared`'s Zod schemas. Items 1–3
+> below are kept for the record with their acceptance met.
+
 1. **[0.A] Scaffold the Turborepo + pnpm workspace** per
    [../project-structure.md](../project-structure.md): a `private` root
    `package.json` (tooling only) with a pinned `packageManager`, `pnpm-workspace.yaml`

eslint.config.mjs

@@ -0,0 +1,62 @@
+// @ts-check
+import js from '@eslint/js';
+import tseslint from 'typescript-eslint';
+import prettier from 'eslint-config-prettier';
+
+/**
+ * Single root ESLint flat config shared by every package (no per-package config
+ * without a justified override). ESLint owns correctness; Prettier owns formatting
+ * (see docs/standards/code-style-typescript.md).
+ *
+ * Type-aware rules (`recommendedTypeChecked`) are scoped to the **TS family**
+ * (`.ts`/`.tsx`/`.mts`/`.cts`) and wired to `projectService`, so they have a program
+ * for every TS variant — including the `.tsx` that arrives with `packages/ui` (0.H).
+ * Attaching type-aware rules to a file with no project crashes ESLint, so JS files get
+ * `disableTypeChecked`. The no-vendor-type-across-the-`@relavium/llm`-seam import fence
+ * (built on the built-in `no-restricted-imports`, per the standard) is wired in 0.F.
+ */
+export default tseslint.config(
+  {
+    // Not source: build output, caches, deps, and tooling/config files (at any depth —
+    // a bare `*.config.*` would only match the repo root, leaving nested per-package
+    // config files to be type-aware-linted with no project, which crashes ESLint).
+    ignores: [
+      '**/dist/**',
+      '**/.turbo/**',
+      '**/coverage/**',
+      '**/node_modules/**',
+      '**/*.config.*',
+    ],
+  },
+  js.configs.recommended,
+  {
+    files: ['**/*.{ts,tsx,mts,cts}'],
+    extends: [...tseslint.configs.recommendedTypeChecked],
+    languageOptions: {
+      parserOptions: {
+        projectService: true,
+        tsconfigRootDir: import.meta.dirname,
+      },
+      // No ambient platform globals here on purpose. Type-aware linting disables
+      // `no-undef` for TS, so globals don't gate undefined names — each package's
+      // tsconfig `types`/`lib` is the real platform boundary (e.g. `@relavium/shared`
+      // sets `types: []`, so `process` is a TS error). Platform globals are added per
+      // surface at its phase: `globals.node` for apps/cli + apps/api + Node tooling;
+      // `globals.browser` for packages/ui + apps/desktop frontend + apps/portal; the
+      // pure engine (`@relavium/core`) and libraries use neither.
+    },
+    rules: {
+      // CLAUDE.md non-negotiables, pinned as errors across the whole TS family.
+      '@typescript-eslint/no-explicit-any': 'error',
+      '@typescript-eslint/no-floating-promises': 'error',
+    },
+  },
+  {
+    // Plain JS (and any stray non-ignored JS): never attach type-aware rules — they
+    // require a TS program and would otherwise crash ESLint on a file with no project.
+    files: ['**/*.{js,jsx,mjs,cjs}'],
+    extends: [tseslint.configs.disableTypeChecked],
+  },
+  // Prettier compatibility must come last — it turns off all formatting rules.
+  prettier,
+);

package.json

@@ -0,0 +1,33 @@
+{
+  "name": "relavium",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "description": "Relavium — multi-surface, local-first AI agent workflow platform (HodeTech). Monorepo root (tooling only).",
+  "packageManager": "pnpm@9.12.3",
+  "engines": {
+    "node": ">=20.11.0",
+    "pnpm": ">=9"
+  },
+  "scripts": {
+    "build": "turbo run build",
+    "lint": "turbo run lint",
+    "typecheck": "turbo run typecheck",
+    "test": "turbo run test",
+    "coverage": "vitest run --coverage",
+    "ci": "turbo run lint typecheck test",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
+  },
+  "devDependencies": {
+    "@eslint/js": "catalog:",
+    "@vitest/coverage-v8": "catalog:",
+    "eslint": "catalog:",
+    "eslint-config-prettier": "catalog:",
+    "prettier": "catalog:",
+    "turbo": "catalog:",
+    "typescript": "catalog:",
+    "typescript-eslint": "catalog:",
+    "vitest": "catalog:"
+  }
+}

packages/core/README.md

@@ -0,0 +1,11 @@
+# `@relavium/core` — placeholder
+
+The engine: YAML→DAG parse, runner, checkpoint/resume, retry. **Zero
+platform-specific imports** — runs identically on every surface. The most important
+package.
+
+> **Not built yet.** This package is a directory placeholder. It is built out in
+> [Phase 1 — engine and LLM](../../docs/roadmap/phases/phase-1-engine-and-llm.md). It has
+> no `package.json` yet, so pnpm/Turborepo do not treat it as a workspace.
+
+Architecture: [shared-core-engine.md](../../docs/architecture/shared-core-engine.md).

packages/db/README.md

@@ -0,0 +1,11 @@
+# `@relavium/db` — placeholder
+
+Drizzle schema + migrations — one schema, two dialects (SQLite local, Postgres
+cloud) ([ADR-0005](../../docs/decisions/0005-sqlite-drizzle-local-postgres-cloud.md)).
+
+> **Not built yet.** This package is a directory placeholder. It is scaffolded in
+> [Phase 0 workstream 0.I](../../docs/roadmap/phases/phase-0-foundations.md) (schema +
+> migrations + SQLite client), ahead of its Phase-1/2 consumers. It has no `package.json`
+> yet, so pnpm/Turborepo do not treat it as a workspace.
+
+Canonical DDL: [database-schema.md](../../docs/reference/desktop/database-schema.md).

packages/llm/README.md

@@ -0,0 +1,11 @@
+# `@relavium/llm` — placeholder
+
+Relavium's own multi-LLM abstraction: the `LLMProvider` seam + thin hand-rolled
+adapters over each provider's official SDK. **No vendor SDK type crosses the seam**
+([ADR-0011](../../docs/decisions/0011-internal-llm-abstraction.md)).
+
+> **Not built yet.** This package is a directory placeholder. It is built out in
+> [Phase 1 — engine and LLM](../../docs/roadmap/phases/phase-1-engine-and-llm.md). It has
+> no `package.json` yet, so pnpm/Turborepo do not treat it as a workspace.
+
+Canonical contract: [llm-provider-seam.md](../../docs/reference/shared-core/llm-provider-seam.md).

packages/shared/README.md

@@ -0,0 +1,32 @@
+# `@relavium/shared`
+
+Zod schemas + inferred TypeScript types — the **single source of truth** for the
+workflow/agent YAML, the run-event union, and config. Every other package depends on
+this one; its only runtime dependency is `zod` (added with the schemas in 0.E).
+
+## Status
+
+**Phase 0 scaffold.** The package builds, type-checks, lints, and tests as the
+dependency root of the graph, exporting `SCHEMA_VERSION` for now. The full schema set
+(`WorkflowSchema`, `AgentSchema`, `NodeSchema`, `EdgeSchema`, the colon-namespaced
+`RunEvent` union, `CostUpdatedEvent`, the human-gate events, `RunSchema`, config) lands
+in [Phase 0 workstream 0.E](../../docs/roadmap/phases/phase-0-foundations.md), driven
+from the frozen contracts in [docs/reference/contracts/](../../docs/reference/contracts/README.md).
+
+## Conventions
+
+- Extends the strict root [`tsconfig.base.json`](../../tsconfig.base.json) and **never
+  loosens a strict flag** — a relaxation needs a justification comment and review
+  ([code-style-typescript.md](../../docs/standards/code-style-typescript.md#strictness)).
+- The public surface is a curated `src/index.ts` — never `export *` of internals.
+- Run-event names are the canonical **colon-namespaced** form with `sequenceNumber` —
+  never the legacy dotted names, never `seqNo`.
+
+## Scripts
+
+| Script | What it does |
+|--------|--------------|
+| `build` | `tsc -p tsconfig.build.json` → `dist/` (emits `.d.ts`; excludes tests) |
+| `typecheck` | `tsc -p tsconfig.json --noEmit` (includes tests) |
+| `lint` | `eslint src` |
+| `test` | `vitest run` |

packages/shared/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@relavium/shared",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "description": "Zod schemas + inferred types — the single source of truth for every Relavium package.",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint src",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "eslint": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  }
+}

packages/shared/src/index.test.ts

@@ -0,0 +1,9 @@
+import { describe, expect, it } from 'vitest';
+
+import { SCHEMA_VERSION } from './index.js';
+
+describe('@relavium/shared scaffold', () => {
+  it('pins the schema version at 1.0', () => {
+    expect(SCHEMA_VERSION).toBe('1.0');
+  });
+});

packages/shared/src/index.ts

@@ -0,0 +1,19 @@
+/**
+ * `@relavium/shared` — Zod schemas + inferred types, the contract source of truth
+ * for every Relavium package and surface.
+ *
+ * **Phase 0 scaffold.** The full schema set — `WorkflowSchema`, `AgentSchema`,
+ * `NodeSchema`, `EdgeSchema`, the colon-namespaced `RunEvent` union, `CostUpdatedEvent`,
+ * the human-gate events, `RunSchema`, and the config schemas — lands in Phase 0
+ * workstream 0.E, driven directly from the frozen reference contracts under
+ * `docs/reference/contracts/`. This entry currently exports only the schema-version
+ * constant so the package is a real, buildable dependency root for the graph.
+ *
+ * The public surface is curated here: never `export *` of internals.
+ */
+
+/** The workflow/agent YAML schema version this package targets. */
+export const SCHEMA_VERSION = '1.0' as const;
+
+/** Inferred type of {@link SCHEMA_VERSION}. */
+export type SchemaVersion = typeof SCHEMA_VERSION;

packages/shared/tsconfig.build.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": false,
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "exclude": ["src/**/*.test.ts", "src/**/*.spec.ts"]
+}

packages/shared/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    // Typecheck-only config: no emit, so rootDir/outDir live in tsconfig.build.json.
+    // `types: []` is the platform-type boundary — no ambient @types/node here, so a
+    // stray `process`/`Buffer` is a TS error (this, not ESLint globals, is the guard).
+    "noEmit": true,
+    "types": []
+  },
+  "include": ["src/**/*.ts"]
+}

packages/ui/README.md

@@ -0,0 +1,7 @@
+# `@relavium/ui` — placeholder
+
+Shared React components: ReactFlow node types + shadcn/ui.
+
+> **Not built yet.** This package is a directory placeholder. It is built out in
+> [Phase 3 — desktop](../../docs/roadmap/phases/phase-3-desktop.md). It has no
+> `package.json` yet, so pnpm/Turborepo do not treat it as a workspace.