@craft-ts/mcp 0.7.0-beta.13

package/dist/catalog.d.ts

@@ -0,0 +1,27 @@
+export declare const DOCS_ORIGIN = "https://craft-ts.github.io/craft";
+export type DocPage = {
+    path: string;
+    title: string;
+    description?: string;
+    body: string;
+};
+export type SkillRecord = {
+    name: string;
+    description: string;
+    markdown: string;
+    references: Record<string, string>;
+};
+export type SearchHit = {
+    path: string;
+    title: string;
+    description?: string;
+    url: string;
+    score: number;
+    snippet: string;
+};
+export declare function pageUrl(path: string): string;
+export declare function searchPages(pages: readonly DocPage[], query: string, options?: {
+    limit?: number;
+    section?: string;
+}): SearchHit[];
+export declare function findPage(pages: readonly DocPage[], path: string): DocPage | undefined;

package/dist/catalog.js

@@ -0,0 +1,67 @@
+export const DOCS_ORIGIN = 'https://craft-ts.github.io/craft';
+function tokenize(value) {
+    return value
+        .toLowerCase()
+        .split(/[^a-z0-9_+*/-]+/)
+        .filter((token) => token.length > 1);
+}
+function countHits(haystack, terms) {
+    return terms.reduce((score, term) => score + (haystack.split(term).length - 1), 0);
+}
+function snippetAround(body, terms) {
+    const lower = body.toLowerCase();
+    const index = terms
+        .map((term) => lower.indexOf(term))
+        .filter((value) => value >= 0)
+        .sort((a, b) => a - b)[0];
+    if (index === undefined) {
+        return body.slice(0, 280).trim();
+    }
+    const start = Math.max(0, index - 80);
+    const excerpt = body.slice(start, start + 280).replace(/\s+/g, ' ').trim();
+    return `${start > 0 ? '…' : ''}${excerpt}${start + 280 < body.length ? '…' : ''}`;
+}
+export function pageUrl(path) {
+    return `${DOCS_ORIGIN}${path === '/' ? '/' : path}`;
+}
+export function searchPages(pages, query, options = {}) {
+    const terms = tokenize(query);
+    if (terms.length === 0)
+        return [];
+    const section = options.section?.replace(/^\//, '');
+    const limit = Math.min(Math.max(options.limit ?? 8, 1), 20);
+    return pages
+        .filter((page) => {
+        if (!section)
+            return true;
+        if (section === 'examples') {
+            return (page.path.startsWith('/learn/') ||
+                page.path.startsWith('/resources/examples'));
+        }
+        return page.path === `/${section}` || page.path.startsWith(`/${section}/`);
+    })
+        .map((page) => {
+        const titleHits = countHits(page.title.toLowerCase(), terms);
+        const pathHits = countHits(page.path.toLowerCase(), terms);
+        const descriptionHits = countHits((page.description ?? '').toLowerCase(), terms);
+        const bodyHits = countHits(page.body.toLowerCase(), terms);
+        const score = titleHits * 12 + pathHits * 8 + descriptionHits * 6 + bodyHits;
+        return {
+            path: page.path,
+            title: page.title,
+            description: page.description,
+            url: pageUrl(page.path),
+            score,
+            snippet: snippetAround(page.body, terms),
+        };
+    })
+        .filter((hit) => hit.score > 0)
+        .sort((a, b) => b.score - a.score || a.path.localeCompare(b.path))
+        .slice(0, limit);
+}
+export function findPage(pages, path) {
+    const normalised = path.startsWith('/') ? path : `/${path}`;
+    return pages.find((page) => page.path === normalised ||
+        page.path === `${normalised.replace(/\/$/, '')}`);
+}
+//# sourceMappingURL=catalog.js.map

package/dist/catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"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"}

package/dist/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/main.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createCraftMcpServer } from './mcp-server.js';
+import { loadCraftMcpResources } from './resources.js';
+const resources = loadCraftMcpResources();
+const server = createCraftMcpServer(resources);
+await server.connect(new StdioServerTransport());
+const shutdown = async () => {
+    await server.close();
+};
+process.once('SIGINT', () => void shutdown());
+process.once('SIGTERM', () => void shutdown());
+//# sourceMappingURL=main.js.map

package/dist/main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAEvD,MAAM,SAAS,GAAG,qBAAqB,EAAE,CAAC;AAC1C,MAAM,MAAM,GAAG,oBAAoB,CAAC,SAAS,CAAC,CAAC;AAE/C,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,oBAAoB,EAAE,CAAC,CAAC;AAEjD,MAAM,QAAQ,GAAG,KAAK,IAAmB,EAAE;IACzC,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;AACvB,CAAC,CAAC;AAEF,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,KAAK,QAAQ,EAAE,CAAC,CAAC;AAC9C,OAAO,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,KAAK,QAAQ,EAAE,CAAC,CAAC"}

package/dist/mcp-server.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type CraftMcpResources } from './resources.js';
+export declare function createCraftMcpServer(resources: CraftMcpResources): McpServer;

package/dist/mcp-server.js

@@ -0,0 +1,144 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { findPage, pageUrl, searchPages } from './catalog.js';
+import { LLMS_FULL_TXT_URL, LLMS_TXT_URL, } from './resources.js';
+export function createCraftMcpServer(resources) {
+    const server = new McpServer({ name: 'craft-ts', version: '0.7.0' });
+    server.registerTool('get_best_practices', {
+        description: 'Return the CraftTS coding-agent guide: which primitive to use, yield* rules, the architecture/ graph contract, services, routes, ESLint, and the AGENTS.md snippet to drop into an app that imports @craft-ts/core. Call this before writing or reviewing Craft code.',
+        annotations: { readOnlyHint: true, destructiveHint: false },
+    }, async () => toolResult({
+        bestPractices: resources.bestPractices,
+        agentsMd: resources.agentsMd,
+        llmsTxt: LLMS_TXT_URL,
+        llmsFullTxt: LLMS_FULL_TXT_URL,
+    }));
+    server.registerTool('search_documentation', {
+        description: 'Search the bundled CraftTS documentation (Learn, Guide, Reference, Resources). Use it when you need the current API, a decision page, or a recipe. Prefer this over guessing from training data.',
+        inputSchema: {
+            query: z.string().min(1).describe('Keywords, API names, or a task'),
+            section: z
+                .enum(['learn', 'guide', 'reference', 'resources', 'examples'])
+                .optional()
+                .describe('Limit results to one docs section. `examples` covers Learn plus /resources/examples.'),
+            limit: z.number().int().positive().max(20).optional(),
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false },
+    }, async ({ query, section, limit }) => toolResult({
+        query,
+        hits: searchPages(resources.pages, query, { section, limit }),
+    }));
+    server.registerTool('get_documentation_page', {
+        description: 'Return one documentation page as markdown. Use a path from search_documentation, such as /guide/state/local-state or /learn/01-first-state.',
+        inputSchema: {
+            path: z
+                .string()
+                .min(1)
+                .describe('Docs path, for example /guide/concepts/mental-model'),
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false },
+    }, async ({ path }) => {
+        const page = findPage(resources.pages, path);
+        if (!page) {
+            return toolResult({
+                error: `No documentation page at ${path}. Call search_documentation first.`,
+            });
+        }
+        return toolResult(serializePage(page));
+    });
+    server.registerTool('find_examples', {
+        description: 'Find Learn tutorials and demo examples that match a task (list, form, pagination, routing, optimistic update, …).',
+        inputSchema: {
+            query: z.string().min(1),
+            limit: z.number().int().positive().max(20).optional(),
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false },
+    }, async ({ query, limit }) => toolResult({
+        query,
+        hits: searchPages(resources.pages, query, {
+            section: 'examples',
+            limit,
+        }),
+    }));
+    server.registerTool('list_skills', {
+        description: 'List Agent Skills shipped with @craft-ts/mcp (architecture tests, routes, spec translation, service migration, full-app migration). Load one with get_skill before following a workflow.',
+        annotations: { readOnlyHint: true, destructiveHint: false },
+    }, async () => toolResult({
+        skills: resources.skills.map(({ name, description, references }) => ({
+            name,
+            description,
+            references: Object.keys(references),
+        })),
+    }));
+    server.registerTool('get_skill', {
+        description: 'Return a CraftTS Agent Skill. Omit `reference` to get SKILL.md; pass a reference filename from list_skills to load that file only.',
+        inputSchema: {
+            name: z
+                .string()
+                .min(1)
+                .describe('Skill directory name, for example craft-ts-routes or translate-spec-to-craft-ts'),
+            reference: z
+                .string()
+                .min(1)
+                .optional()
+                .describe('Optional references/*.md filename'),
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false },
+    }, async ({ name, reference }) => {
+        const skill = resources.skills.find((entry) => entry.name === name);
+        if (!skill) {
+            return toolResult({
+                error: `Unknown skill "${name}". Call list_skills.`,
+                available: resources.skills.map((entry) => entry.name),
+            });
+        }
+        if (!reference) {
+            return toolResult({
+                name: skill.name,
+                description: skill.description,
+                markdown: skill.markdown,
+                references: Object.keys(skill.references),
+            });
+        }
+        const markdown = skill.references[reference];
+        if (!markdown) {
+            return toolResult({
+                error: `Skill "${name}" has no reference "${reference}".`,
+                available: Object.keys(skill.references),
+            });
+        }
+        return toolResult({ name: skill.name, reference, markdown });
+    });
+    server.registerTool('get_llms_txt', {
+        description: 'Return the public llms.txt / llms-full.txt URLs and a short index of bundled documentation paths. Use llms.txt as the internet entry point; use search_documentation for offline lookup.',
+        annotations: { readOnlyHint: true, destructiveHint: false },
+    }, async () => toolResult({
+        llmsTxt: LLMS_TXT_URL,
+        llmsFullTxt: LLMS_FULL_TXT_URL,
+        markdownPages: resources.pages.map((page) => ({
+            path: page.path,
+            title: page.title,
+            url: `${pageUrl(page.path)}.md`,
+        })),
+    }));
+    return server;
+}
+function serializePage(page) {
+    return {
+        path: page.path,
+        title: page.title,
+        description: page.description,
+        url: pageUrl(page.path),
+        markdownUrl: `${pageUrl(page.path)}.md`,
+        markdown: page.body,
+    };
+}
+function toolResult(result) {
+    return {
+        content: [
+            { type: 'text', text: JSON.stringify(result, null, 2) },
+        ],
+        structuredContent: { result },
+    };
+}
+//# sourceMappingURL=mcp-server.js.map

package/dist/mcp-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-server.js","sourceRoot":"","sources":["../src/mcp-server.ts"],"names":[],"mappings":"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"}

package/dist/resources.d.ts

@@ -0,0 +1,10 @@
+import { type DocPage, type SkillRecord } from './catalog.js';
+export declare const LLMS_TXT_URL = "https://craft-ts.github.io/craft/llms.txt";
+export declare const LLMS_FULL_TXT_URL = "https://craft-ts.github.io/craft/llms-full.txt";
+export type CraftMcpResources = {
+    pages: DocPage[];
+    skills: SkillRecord[];
+    bestPractices: string;
+    agentsMd: string;
+};
+export declare function loadCraftMcpResources(moduleUrl?: string): CraftMcpResources;

package/dist/resources.js

@@ -0,0 +1,63 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { DOCS_ORIGIN } from './catalog.js';
+export const LLMS_TXT_URL = `${DOCS_ORIGIN}/llms.txt`;
+export const LLMS_FULL_TXT_URL = `${DOCS_ORIGIN}/llms-full.txt`;
+function packageRootFrom(moduleUrl) {
+    return join(dirname(fileURLToPath(moduleUrl)), '..');
+}
+function parseSkillFrontmatter(markdown) {
+    if (!markdown.startsWith('---')) {
+        throw new Error('Skill is missing YAML frontmatter.');
+    }
+    const end = markdown.indexOf('\n---', 3);
+    if (end === -1) {
+        throw new Error('Skill frontmatter is not closed.');
+    }
+    const frontmatter = markdown.slice(3, end);
+    const name = /^name:\s*(.+)$/m.exec(frontmatter)?.[1]?.trim();
+    const description = /^description:\s*(.+)$/m
+        .exec(frontmatter)?.[1]
+        ?.trim();
+    if (!name || !description) {
+        throw new Error('Skill frontmatter must include name and description.');
+    }
+    return { name, description, body: markdown };
+}
+function loadSkill(directory) {
+    const markdown = readFileSync(join(directory, 'SKILL.md'), 'utf8');
+    const parsed = parseSkillFrontmatter(markdown);
+    const references = {};
+    const referencesDir = join(directory, 'references');
+    if (existsSync(referencesDir)) {
+        for (const file of readdirSync(referencesDir)) {
+            if (!file.endsWith('.md'))
+                continue;
+            references[file] = readFileSync(join(referencesDir, file), 'utf8');
+        }
+    }
+    return {
+        name: parsed.name,
+        description: parsed.description,
+        markdown: parsed.body,
+        references,
+    };
+}
+export function loadCraftMcpResources(moduleUrl = import.meta.url) {
+    const root = packageRootFrom(moduleUrl);
+    const pages = JSON.parse(readFileSync(join(root, 'content/docs-index.json'), 'utf8'));
+    const skillsRoot = join(root, 'skills');
+    const skills = readdirSync(skillsRoot)
+        .map((name) => join(skillsRoot, name))
+        .filter((directory) => existsSync(join(directory, 'SKILL.md')))
+        .map(loadSkill)
+        .sort((a, b) => a.name.localeCompare(b.name));
+    return {
+        pages,
+        skills,
+        bestPractices: readFileSync(join(root, 'content/best-practices.md'), 'utf8'),
+        agentsMd: readFileSync(join(root, 'content/agents.md'), 'utf8'),
+    };
+}
+//# sourceMappingURL=resources.js.map

package/dist/resources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resources.js","sourceRoot":"","sources":["../src/resources.ts"],"names":[],"mappings":"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"}

package/mcp.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
+  "mcpServers": {
+    "craft-ts": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["./dist/main.js"]
+    }
+  }
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@craft-ts/mcp",
+  "version": "0.7.0-beta.13",
+  "description": "MCP server, Agent Skills, and LLM files for coding agents using @craft-ts/core",
+  "author": "Romain Geffrault",
+  "license": "MIT",
+  "homepage": "https://craft-ts.github.io/craft/resources/ai-agents",
+  "bugs": {
+    "url": "https://github.com/craft-ts/craft-ts/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/craft-ts/craft-ts.git",
+    "directory": "packages/mcp"
+  },
+  "type": "module",
+  "bin": {
+    "craft-ts-mcp": "dist/main.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "content",
+    "plugin.json",
+    "mcp.json",
+    "README.md",
+    "!dist/**/*.spec.js",
+    "!dist/**/*.spec.d.ts",
+    "!dist/**/*.spec.js.map"
+  ],
+  "scripts": {
+    "bundle-docs": "node scripts/bundle-docs.mjs",
+    "build": "node scripts/build.mjs",
+    "start": "npm run build && node dist/main.js",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.26.0",
+    "zod": "4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "20.19.9",
+    "typescript": "6.0.3",
+    "vitest": "^4.0.8"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "craft-ts",
+    "craft-ts",
+    "angular",
+    "mcp",
+    "mcp-server",
+    "llms.txt",
+    "agent-skills",
+    "ai"
+  ]
+}

package/plugin.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "craft-ts",
+  "description": "Agent Skills and MCP server for writing framework-independent @craft-ts/core apps: primitives, API boundaries, architecture tests, services, routes, forms, Effect v4, and migration.",
+  "author": {
+    "name": "Romain Geffrault",
+    "url": "https://github.com/craft-ts/craft-ts"
+  },
+  "homepage": "https://craft-ts.github.io/craft/resources/ai-agents",
+  "repository": "https://github.com/craft-ts/craft-ts",
+  "license": "MIT",
+  "keywords": [
+    "angular",
+    "craft-ts",
+    "craft-ts",
+    "mcp",
+    "agent-skills"
+  ]
+}

package/skills/craft-ts/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: craft-ts
+description: Write and review framework-independent @craft-ts/core applications, including CSR and SSR. Use when creating or evolving a CraftTS project, adding state, query, mutation, queryParams, asyncProcess, craftService, craftComponent, craftRoutes, forms, SSR rendering or hydration, API boundaries, or coding-agent setup.
+---
+
+# CraftTS
+
+You are working in a framework-independent application that depends on
+`@craft-ts/core`. The default renderer is `@craft-ts/component`; Angular is not
+required and must not be introduced just to solve a Craft problem.
+
+## First steps
+
+1. Call the CraftTS MCP tool `get_best_practices` when it is available.
+2. Search docs with `search_documentation` before inventing an API.
+3. Load a workflow skill with `get_skill` when the task matches:
+   - `craft-ts-architecture-tests` — scaffold or run `architecture/`, or freeze a graph smell. Not before every feature.
+   - `translate-spec-to-craft-ts` — map a spec onto primitives
+   - `craft-ts-routes` — type-safe routes and DI checks
+   - `craft-ts-service-migration` — Angular services → `craftService`
+   - `migrate-to-craft-ts` — run `craft-migrate`, then finish diagnostics
+   - `craft-ts-effect-v4` — use Effect v4 services, Layers and `queryEffect`
+
+If MCP is not configured, read https://ng-angular-stack.github.io/craft/llms.txt and the `AGENTS.md` snippet in this package (`content/agents.md`).
+
+## Hard rules
+
+- `yield*` every Craft reader. Use `craftUse` only at synchronous boundaries.
+- `state` / `query` / `mutation` / `queryParams` / `asyncProcess` — not `signal()`.
+- One insertion per primitive; compose with `craftPipe`.
+- `craftService` + generated `X()` helpers. No new `inject()` / `@Injectable`.
+- `craftRoutes` + `componentDeps` + a per-file DI check. Split on `TS2589`.
+- Use `startCraft` and `provideCraftRouter` for a browser app that may receive
+  SSR HTML. It hydrates a host marked by Craft SSR and mounts a fresh client
+  tree otherwise. Use `bootstrapCraft` when a fresh client mount is explicitly
+  required, and `hydrateCraft` when hydration must be forced or customized.
+- Use `renderCraft` for one isolated SSR request. Create a new render per
+  request; never reuse its injector, platform, primitive registry, or history.
+- Keep SSR data behavior explicit with `pendingBlock({ ssr: 'block' | 'fallback' | 'client' })`
+  or a route-level `ssr` policy. Do not let a suspended source reach SSR
+  without a policy.
+- Run existing architecture tests. Do not add an architecture rule for the feature.
+- Confirm symbols against the installed `node_modules/@craft-ts/core`.

package/skills/craft-ts-architecture-tests/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: craft-ts-architecture-tests
+description: Use when scaffolding or running a CraftTS architecture suite (architecture/, craft-migrate-architecture, nx architecture, assertRouteDiProofs, assertDeclarativeArchitecture), when a graph smell must not recur (duplicate HTTP, feature leak, mutation without insertReactOnMutation, unarmed CanRun, craftUnique clash), or when an app that imported @craft-ts/core has no architecture/ folder at bootstrap or after craft-migrate.
+---
+
+# CraftTS architecture tests
+
+The `architecture/` suite is the app's **graph contract**. It proves who may
+depend on whom, which HTTP endpoint is owned once, which identity appears
+once — without booting a browser framework. It works for framework-independent
+CraftTS apps as well as migrated Angular apps.
+
+Setup and helpers: https://ng-angular-stack.github.io/craft/guide/testing/architecture
+Do not copy that page. Load it with `get_documentation_page` when you need a
+signature.
+
+## When not to use
+
+Do **not** add an architecture rule for the feature. A new `it()` is not part
+of mapping a spec onto primitives. Write application code, then **run** the
+suite that already exists.
+
+## 1. Bootstrap a new project
+
+Prefer `craft create`, which asks for Effect v4 and agent integrations and
+generates the application, API/page example, routes, ESLint, unit tests,
+architecture suite and Playwright commands together:
+
+```shell
+npx craft create my-app --effect=none --agents=codex,cursor,cloud-code
+```
+
+For an Effect v4 starter:
+
+```shell
+npx craft create my-app --effect=v4 --agents=codex
+```
+
+The generated `README.md` is the command contract. The starter's architecture
+suite is ready at bootstrap; do not postpone it until after the first feature.
+
+## 2. Bootstrap an existing project
+
+Use at app start or as the last `craft-migrate` step, when `architecture/` is
+missing.
+
+```shell
+npx craft-migrate-architecture --project tsconfig.app.json --root src --write
+```
+
+That writes the Vitest/Node suite, catalog, baseline rules, and an Nx
+`architecture` target or package script. Enable the scaffolded helpers
+(`assertDeclarativeArchitecture`, `assertRouteDiProofs`, and the files under
+`architecture/rules/`). Point CI at `npx nx architecture <app>` (or
+`npx vitest run --config vitest.architecture.config.ts`).
+
+If this comes up **mid-feature**, report the gap and offer the scaffold. Do
+not impose it.
+
+## 3. During a feature
+
+Run the existing suite. A failure is a graph slip in the **code** (or a
+disarmed DI proof), not a missing `it()`.
+
+```shell
+npx nx architecture <app>
+```
+
+Do not add an architecture rule for the feature.
+
+## 4. Encode a smell
+
+When a pattern should not recur — duplicate HTTP, feature leak, mutation
+with no `insertReactOnMutation`, duplicate `craftUnique`, commented `CanRun`,
+`craftEffect` pushing into another primitive — freeze it.
+
+- If `architecture/` exists, add the matching helper (or a neighbourhood
+  `it()`) under `architecture/rules/`.
+- If it does not, propose workflow 1 first, then the rule.
+
+Keep the assertion next to a comment that states the **product** invariant.
+
+| Smell | Helper |
+| --- | --- |
+| Duplicate `craftUnique` identity, or a non-literal argument | `assertCraftUnique` |
+| Same HTTP verb+URL from two sites | `assertHttpEndpointUnique` |
+| `craftComputed` calls a method or writes `source$` | `assertCraftComputedPure` |
+| `depends-on` cycle | `assertNoDependencyCycles` |
+| Mutation with no `insertReactOnMutation` | `assertMutationHasReactOn` |
+| The five declarative checks together | `assertDeclarativeArchitecture` |
+| Unarmed `CanRun` / missing route or error-screen proof | `assertRouteDiProofs` |
+| `depends-on` crosses a folder allowlist | `assertPathBoundaries` |
+| Two feature branches leak into each other | `noExclusiveLink` |
+| Persister without `craftUnique` | `assertPersistedPrimitiveHasUnique` |
+| Same `insertSelect` key twice on one host | `assertInsertSelectUnique` |
+| `craftEffect` calls HTTP or a mutation | `assertCraftEffectNoNetwork` |
+| Duplicate `data-craft-name` on interactive elements, or a missing / non-literal first-argument name | `assertInteractiveElementNamed` |
+
+Custom lookups (`graph.route`, `graph.providedOn`, `outgoing`) are for
+invariants the helpers do not cover.
+
+## Red flags
+
+| Excuse | Reality |
+| --- | --- |
+| "I'll add a rule for this feature first" | Rules are baseline or anti-regression, not TDD-before-feature. |
+| "Too small to encode" | If it must not recur, it is a rule. |
+| "We'll add architecture tests after the PR" | The smell will ship. Encode it now or say you are not encoding it. |
+| "ESLint already covers this" | ESLint is local. The suite is graph-wide. |
+| "The suite is missing, I'll skip it" | Offer the scaffold. Do not pretend the contract exists. |

package/skills/craft-ts-effect-v4/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: craft-ts-effect-v4
+description: Build Effect v4 integrations in framework-independent CraftTS applications with typed services, Layers, queryEffect and Effect diagnostics. Use when a project selected EffectTS during craft create or when editing Effect domain code.
+---
+
+# CraftTS + Effect v4
+
+Use this skill only when the project has selected EffectTS. The project must
+use the Effect v4 line (`effect@4.0.0-rc.*` or a later v4 release), never v3
+examples copied from older documentation.
+
+## Boundary
+
+- Domain operations return `Effect.Effect` and depend on `Context.Service`.
+- Production implementations are supplied by `Layer` and registered once in
+  the Craft app config.
+- UI data loading uses `queryEffect`; do not call `Effect.runPromise` from a
+  component or bypass the Craft reactive lifecycle.
+- Install `installCraftEffectBridge()` once during bootstrap.
+- Run the Effect diagnostics command from `package.json` after changing an
+  Effect generator, service, schema or Layer.
+
+## Verification
+
+Run the focused test, `npm run effect-check`, `npm run lint`,
+`npm run typecheck`, `npm run architecture`, and the E2E flow when the browser
+contract changed. The architecture suite checks that Effect resources keep a
+typed service boundary and that the declarative Craft graph remains intact.
+
+Confirm symbols against the installed v4 package. Do not “fix” a v4 diagnostic
+by downgrading the dependency or importing an Angular adapter.