Getting Started

Greenfield — blueprint init

npx @kekkai/blueprint init

One command, and your design philosophy has guardrails in place:

• src/<layer>/ folders for every declared layer
• blueprint.config.mjs — the single source of truth
• eslint.config.mjs — structural rules plus the third-party core
• docs/architecture-handbook.md and agent contracts (CLAUDE.md, AGENTS.md)
• compilerOptions.paths wired into tsconfig.json / jsconfig.json
• .github/workflows/blueprint-ci.yml — lint + inspect as the gate

The framework is auto-detected from package.json (--framework vue|react only breaks ties). An existing eslint config is never overwritten — init prints a merge snippet instead (only the config init generated itself, marked by its first-line banner, is regenerated in place). Re-running init is idempotent.

Brownfield — blueprint inspect

npx @kekkai/blueprint inspect

Read-only. Scans src/, checks it against the blueprint, and prints an Architecture Report with migration steps. Any error-level finding exits 1.

A legacy project's first report is a wall of red — that is what the baseline ratchet is for:

npx @kekkai/blueprint inspect --update-baseline   # lock today's debt
npx @kekkai/blueprint inspect --baseline          # CI: fail only on NEW findings

From the moment adoption completes, AI-collaboration output becomes controllable and reviewable — the codebase stops getting worse. As debt is paid down, baseline records that are no longer needed get surfaced for removal, so the ratchet keeps tightening. A zero-finding repo needs no baseline file at all — --baseline treats a missing file as an empty baseline.

Blast radius — blueprint deps

npx @kekkai/blueprint deps hooks/useCart   # who imports it, what it imports
npx @kekkai/blueprint deps                 # leaderboard: every module by fan-in

Read-only fan-in / fan-out per module — "who gets hit if I change this". Output samples, granularity, and graph boundaries: Blast Radius — deps.

The Blueprint

// blueprint.config.mjs
import { defineBlueprint } from '@kekkai/blueprint';

export default defineBlueprint({
  framework: 'vue',
  architecture: {
    alias: '~app',
    layers: [
      { name: 'components', does: 'Reusable, presentational UI', mustNot: ['call services'] },
      { name: 'hooks', does: 'Adapts server and shared state' },
      {
        name: 'services',
        does: 'Network primitives',
        owns: ['axios', { global: 'fetch' }],
        allowedImporters: ['hooks'],
      },
    ],
    flow: 'one-way',
    module: { layout: 'folder', entry: 'index', private: ['hooks', 'styles', 'types'] },
  },
});

Or start from a canonical preset — vuePreset() / reactPreset() encode the full governance handbook: six layers, ten principles, seven component-shape axes, and an eighteen-rule working playbook. That content is documented page by page in Philosophy; see the API Reference for every export.