create-astram-app 0.1.1 → 0.1.3

package/dist/index.js

@@ -20,7 +20,7 @@
  *
  * Reference skeleton: `examples/example-backend/` in the astram-framework repo.
  */
-import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 /** Token substituted with the app name at copy time (in package.json name, README title, …). */
@@ -152,30 +152,47 @@ export function main(argv = process.argv.slice(2)) {
     if (report.skipped.length > 0) {
         console.log(`  ${report.skipped.length} existing file(s) left untouched (never-clobber): ${report.skipped.join(', ')}`);
     }
-    console.log('\nWhat you got:');
-    console.log('  • A running, framework-ENFORCED NestJS app — every route is denied by');
-    console.log('    default (ADR-0002) unless you classify it with @Public()/@Classified().');
-    console.log('  • The framework installed as immutable dependencies (@astram/core,');
-    console.log('    @astram/guard, @astram/sdk) — you never edit it; upgrade via `npm update`.');
-    console.log('  • An empty src/features/ — your editable space. Add a feature by writing a');
-    console.log('    Nest module/controller there and registering it in src/app.module.ts.');
+    console.log('\nWhat you got (a monorepo):');
+    console.log('  • server/  — a running, framework-ENFORCED NestJS API. Every route is denied');
+    console.log('    by default (ADR-0002) unless you classify it @Public()/@Classified().');
+    console.log('  • frontend/ — an empty space for your UI (add any framework: Vite/React, etc.).');
+    console.log('  • The framework installed in server/ as immutable dependencies (@astram/core,');
+    console.log('    @astram/guard, @astram/engine, @astram/sdk) — you never edit it; upgrade via');
+    console.log('    `npm update`.');
+    console.log('  • server/src/features/ — your editable API space. Add a feature by writing a');
+    console.log('    Nest module/controller there and registering it in server/src/app.module.ts.');
     console.log('  • .astram/guide/ — your own, upgrade-safe project-rules space (ADR-0025).');
     console.log('\n  (A turnkey login/session boilerplate ships in a later framework release;');
     console.log('   today the app gives you correct-by-default ENFORCEMENT out of the box.)');
     console.log('\nNext steps:');
-    console.log(`  cd ${appName}`);
+    console.log(`  cd ${appName}/server`);
     console.log('  npm install');
-    console.log('  npm run dev        # boots the app; GET /health → 200, unclassified → 403');
+    console.log('  npm run dev        # boots the API; GET /health → 200, unclassified → 403');
     console.log('');
     return 0;
 }
 // Run ONLY when this module is the process entry point (i.e. executed as the
 // CLI), NOT when imported by a test. Keyed on the actual entry script rather
-// than NODE_ENV, so a consumer whose shell happens to export NODE_ENV=test
-// still gets a working `npx create-astram-app` (avoids a silent no-op).
-const invokedAsCli = process.argv[1] !== undefined &&
-    import.meta.url === pathToFileURL(process.argv[1]).href;
-if (invokedAsCli) {
+// than NODE_ENV (so a consumer whose shell exports NODE_ENV=test still gets a
+// working CLI). CRITICAL: `npx`/npm run the package through a `bin` SYMLINK, so
+// `process.argv[1]` is the symlink path, not this real dist file — we must
+// resolve it (realpath) before comparing, or `import.meta.url` (the real file)
+// never matches and the CLI silently no-ops. When imported by a test, argv[1]
+// is the test runner, which resolves to a different real file → correctly skips.
+function isInvokedAsCli() {
+    const entry = process.argv[1];
+    if (entry === undefined)
+        return false;
+    const thisFile = fileURLToPath(import.meta.url);
+    try {
+        return realpathSync(entry) === realpathSync(thisFile);
+    }
+    catch {
+        // If either path can't be realpath'd, fall back to a direct compare.
+        return pathToFileURL(entry).href === import.meta.url;
+    }
+}
+if (isInvokedAsCli()) {
     process.exitCode = main();
 }
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-astram-app",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "license": "MIT",
   "description": "Scaffolder for a new Astram app — emits a running, framework-enforced consumer project (empty src/features/ + deny-by-default enforcement) that installs the immutable @astram/core, @astram/guard, and @astram/sdk framework.",
   "type": "module",

package/template/CLAUDE.md

@@ -0,0 +1,51 @@
+# __APP_NAME__ — AI guide (entry)
+
+This is the entry point for AI assistants (Claude Code) and teammates. It ties together
+the **two-layer guide** (ADR-0025): the framework's rules (the floor) + this app's own
+rules (on top). Read both before doing any work.
+
+## 1. Framework rules — the FLOOR (framework-owned, refreshed on upgrade)
+
+The Astram framework ships its hard rules + capabilities in the installed
+`@astram/guide` package. They are synced into `.claude/rules/` (do NOT edit those
+copies — they are regenerated from the framework package on every install/upgrade):
+
+- **`.claude/rules/astram-framework-rules.md`** — the non-negotiable rules: never edit
+  the framework, all data through the RecordEngine pipe, classify every route,
+  **STOP-and-flag a gap** instead of working around it, fail closed, and — after any
+  framework upgrade — **re-read these rules first** (Rule 0).
+- **`.claude/rules/astram-framework-capabilities.md`** — what the framework provides
+  this version (check here before building; if it's not there, it's a gap → flag it).
+
+@./.claude/rules/astram-framework-rules.md
+
+> These are a FLOOR: this app's own rules (below) may ADD to or TIGHTEN them, but never
+> weaken them. The never-touch-core / never-bypass-enforcement rules are absolute.
+
+## 2. Your project's rules — the project layer (yours, never touched by an upgrade)
+
+Your project-specific rules, conventions, and the framework-gap log live in
+**`.astram/guide/`** (git-tracked, developer-owned — a framework upgrade never touches
+it):
+
+- **`.astram/guide/README.md`** — what this layer is + how it relates to the framework.
+- **`.astram/guide/gaps.md`** — the framework capability gaps you've flagged (create it
+  the first time you hit one — the gap-flag loop).
+
+Add your own rules as markdown files in `.astram/guide/`.
+
+## 3. Keeping the framework rules current (the upgrade flow)
+
+The framework rules in `.claude/rules/` are a **generated mirror** of the installed
+`@astram/guide` package. They refresh automatically:
+
+- `server/`'s `postinstall` runs `sync-astram-guide` on every `npm install` / `npm
+  update`, copying the current framework rules into `.claude/rules/`.
+- To refresh manually: `cd server && npm run guide:sync`.
+- The synced framework files + `.claude/rules/.astram-guide-version` are **gitignored**
+  (they belong to the framework version, not your app). Your `.astram/guide/` layer is
+  git-tracked and yours.
+
+**On a framework upgrade:** run `npm update` (or `npm install`) in `server/` — the
+framework rules refresh to the new version, your `.astram/guide/` rules are untouched,
+then re-read the refreshed `.claude/rules/astram-framework-rules.md` (Rule 0).

package/template/README.md

@@ -1,24 +1,37 @@
 # __APP_NAME__
 
-An **Astram consumer app**, scaffolded with `create-astram-app`. It depends on the
-published, immutable framework packages ([`@astram/core`](https://www.npmjs.com/package/@astram/core),
+An **Astram consumer app**, scaffolded with `create-astram-app`. A monorepo with a
+`server/` (the API) and a `frontend/` (your UI). The API depends on the published,
+immutable framework packages ([`@astram/core`](https://www.npmjs.com/package/@astram/core),
 [`@astram/guard`](https://www.npmjs.com/package/@astram/guard),
+[`@astram/engine`](https://www.npmjs.com/package/@astram/engine),
 [`@astram/sdk`](https://www.npmjs.com/package/@astram/sdk)) and enforces
-**deny-by-default** from the very first boot. You build features; the framework
-lives read-only in `node_modules` and upgrades via `npm update` — you never edit it.
+**deny-by-default** from the very first boot. You build features; the framework lives
+read-only in `server/node_modules` and upgrades via `npm update` — you never edit it.
 
-## Run it
+## Layout
+
+```
+__APP_NAME__/
+  server/       the API (NestJS + the Astram framework enforcement)
+  frontend/     your UI (empty — add Vite/React/Next/… and call the API)
+  .astram/      your project-owned, upgrade-safe AI/dev guide (ADR-0025)
+  docs/         your own docs (the scaffolder never clobbers this)
+```
+
+## Run the API
 
 ```bash
+cd server
 npm install
-npm run dev        # boots the app (tsx watch) on http://localhost:3000
+npm run dev        # boots the API (tsx watch) on http://localhost:3000
 ```
 
 Then:
 
 ```bash
-curl -i localhost:3000/health          # 200 — @Public health probe
-curl -i localhost:3000/demo/public     # 200 — explicit @Public() opt-out
+curl -i localhost:3000/health              # 200 — @Public health probe
+curl -i localhost:3000/demo/public         # 200 — explicit @Public() opt-out
 curl -i localhost:3000/demo/unclassified   # 403 — DENIED (no classification)
 ```
 
@@ -26,12 +39,13 @@ That last 403 is the whole point: **every route is denied unless you explicitly
 classify it.** Forgetting to declare a route locks the door instead of silently
 exposing it.
 
-Other scripts: `npm run build` (→ `dist/`), `npm start` (run the build),
-`npm test` (the enforcement e2e), `npm run lint`.
+Other `server/` scripts: `npm run build` (→ `dist/`), `npm start` (run the build),
+`npm test`, `npm run lint`.
 
-## How it wires the framework
+## How the API wires the framework
 
-`src/app.module.ts` imports the ONE registration seam — no local security wiring:
+`server/src/app.module.ts` imports the ONE registration seam — no local security
+wiring:
 
 ```ts
 import { ShieldModule } from '@astram/guard';
@@ -45,45 +59,30 @@ export class AppModule {}
 
 `ShieldModule.forRoot()` binds the global deny-by-default guard (ADR-0002), the
 boot-pool assertion (ADR-0018), and the Core decision-authority token. You never
-re-implement enforcement — you register it once and add your controllers.
+re-implement enforcement — you register it once and add your controllers. Enable the
+full auth surface (login/MFA/refresh/logout) with `ShieldModule.forRoot({ auth: true,
+credentialResolver, decisionAuthority })`.
 
 ## Add a feature (the framework way)
 
-1. Create `src/features/<your-feature>/` with a Nest module + controller(s).
-2. Register it in `src/app.module.ts` (add the module to `imports`, or its
+1. Create `server/src/features/<your-feature>/` with a Nest module + controller(s).
+2. Register it in `server/src/app.module.ts` (add the module to `imports`, or its
    controller to `controllers`).
-3. **Classify every route:** `@Public()` for open routes, `@Classified(...)` for
-   guarded ones. Anything unclassified is denied (403) by design.
-4. Add a test (see `test/enforcement.e2e.spec.ts` for the pattern).
+3. **Classify every route:** `@Public()` for open routes, `@Classified({ typeKey,
+   action })` for guarded ones. Anything unclassified is denied (403) by design.
+4. **Data access goes through the framework's RecordEngine** — never a raw DB pool.
+   The `server/eslint.config.js` wall rule fails the build on off-road DB access.
+5. Add a test (see `server/test/` for the pattern).
 
-`src/features/` starts empty — it's your space.
+`server/src/features/` starts empty — it's your space.
 
-## What's here today (and what's next)
+## The frontend
 
-Today you get correct-by-default **enforcement** out of the box: the framework's
-guard protects every route from the first boot. A turnkey **login / session**
-boilerplate (wired through the same `ShieldModule.forRoot()` seam) arrives in a
-later framework release — when it lands, you'll pick it up via `npm update` without
-touching your `src/`.
-
-## Layout
-
-```
-src/
-  main.ts                   HTTP bootstrap (thin) — loadAppConfig from @astram/guard
-  app.module.ts             declares enforcement via ShieldModule.forRoot()
-  health/
-    health.controller.ts    /health /ready /live  (all @Public)
-    demo.controller.ts      /demo/public (@Public) + /demo/unclassified (denied)
-  features/                 EMPTY — your editable space
-test/
-  enforcement.e2e.spec.ts   boots the app; proves 200 health + 403 unclassified
-.astram/guide/              YOUR project guide (upgrade-safe; never touched)
-docs/                       your own docs (the scaffolder never clobbers this)
-```
+`frontend/` is intentionally empty — Astram is a **backend security kernel**, so it
+does not impose a UI framework. Add whatever you like and call the API. See
+`frontend/README.md` for the auth endpoints your UI will consume.
 
 ## The `.astram/guide/` directory
 
-This is your **project-owned** AI/dev guide layer (ADR-0025) — framework upgrades
-never touch it. Put your project's own rules and context there. See
-`.astram/guide/README.md`.
+Your **project-owned** AI/dev guide layer (ADR-0025) — framework upgrades never touch
+it. Put your project's own rules and context there. See `.astram/guide/README.md`.

package/template/_gitignore

@@ -3,3 +3,9 @@ dist/
 .env
 *.log
 .DS_Store
+
+# The framework rules synced from @astram/guide (ADR-0025) — a GENERATED mirror of
+# the installed framework version, refreshed on every install/upgrade. Not yours to
+# edit or commit. (Your OWN rules live in .astram/guide/, which IS git-tracked.)
+.claude/rules/astram-framework-*.md
+.claude/rules/.astram-guide-version

package/template/frontend/README.md

@@ -0,0 +1,16 @@
+# frontend
+
+Your UI lives here. This folder is intentionally empty — the Astram framework is a
+**backend security kernel**, so it does not impose a frontend framework. Add whatever
+you like (Vite + React, Next.js, SvelteKit, a mobile app's web build, …) and point it
+at the API in `../server` (default `http://localhost:3000`).
+
+The API's auth surface is ready to consume:
+
+- `POST /auth/login` `{ identityHint, password }` → `{ session, tokens: { accessToken, refreshToken } }`
+- `POST /auth/refresh` `{ refreshToken }` → new tokens
+- `POST /auth/logout` `{ sessionId }` → 204
+- Protected routes: send `Authorization: Bearer <accessToken>`. A `@Classified` route
+  is enforced by the framework — no token → 401, denied by policy → 403.
+
+See `../server/src/features/` for the API features your UI will call.

package/template/server/eslint.config.js

@@ -0,0 +1,95 @@
+// ESLint flat config for an Astram consumer app.
+//
+// ─────────────────────────────────────────────────────────────────────────────
+// THE PHYSICAL WALL — backstop (do not remove).
+//
+// The Astram paved road is the ONE way features touch data: inject the framework's
+// RecordEngine (from @astram/engine) and go through the pipe (permission gate +
+// audit are mandatory, cross-tenant isolation is enforced). A feature must NEVER
+// reach the database directly — a raw mariadb/typeorm pool, a DataSource, a
+// QueryRunner, or a repository `.save()`/`.query()` skips the security layer
+// entirely (this is exactly how astram-org's ORS got bypassed 165 times).
+//
+// The PRIMARY wall is structural: the framework never hands feature scope a pool
+// (EngineModule seals it). THIS lint rule is the BACKSTOP: it fails the build if a
+// file under `src/features/**` imports a raw DB symbol or calls a raw DB method, so
+// an off-road attempt is a red build, not a silent success.
+//
+// If you hit this rule because the pipe can't do what you need: STOP. Do NOT work
+// around it. Record the gap in `.astram/guide/gaps.md` and raise it with the
+// framework — the capability must be added to @astram/engine (the gap-flag loop).
+// ─────────────────────────────────────────────────────────────────────────────
+
+import js from '@eslint/js';
+import tseslint from 'typescript-eslint';
+
+/** Raw DB packages a feature must never import directly. */
+const FORBIDDEN_DB_IMPORTS = [
+  { name: 'mariadb', message: 'Wall: features never open a DB pool — use the RecordEngine (@astram/engine).' },
+  { name: 'mysql', message: 'Wall: features never open a DB driver — use the RecordEngine (@astram/engine).' },
+  { name: 'mysql2', message: 'Wall: features never open a DB driver — use the RecordEngine (@astram/engine).' },
+  { name: 'typeorm', message: 'Wall: no ORM in features — use the RecordEngine (@astram/engine).' },
+  { name: '@nestjs/typeorm', message: 'Wall: no ORM in features — use the RecordEngine (@astram/engine).' },
+  { name: 'pg', message: 'Wall: features never open a DB driver — use the RecordEngine (@astram/engine).' },
+  { name: 'knex', message: 'Wall: no query builder in features — use the RecordEngine (@astram/engine).' },
+];
+
+/**
+ * Named imports that hand a feature raw DB access even from an ALLOWED package.
+ * `SHIELD_DB_POOL` is exported from `@astram/guard` (a package a feature legitimately
+ * imports for other reasons), so it must be blocked by NAME on that path — the engine
+ * owns the pool; feature scope must never import the pool token.
+ */
+const FORBIDDEN_DB_NAMED_FROM = [
+  {
+    name: '@astram/guard',
+    importNames: ['SHIELD_DB_POOL'],
+    message: 'Wall: the DB pool is sealed inside the engine — features use the RecordEngine (@astram/engine).',
+  },
+];
+
+export default tseslint.config(
+  js.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    ignores: ['dist/**', 'node_modules/**'],
+  },
+  // ── The wall: scoped to feature code ──────────────────────────────────────
+  {
+    files: ['src/features/**/*.ts'],
+    rules: {
+      'no-restricted-imports': [
+        'error',
+        {
+          paths: [...FORBIDDEN_DB_IMPORTS, ...FORBIDDEN_DB_NAMED_FROM],
+          patterns: [
+            {
+              group: ['**/adapters/mariadb-*', '@astram/engine/dist/adapters/*'],
+              message:
+                'Wall: the engine adapters (pool/uow/audit) are framework-internal — features use the RecordEngine facade only.',
+            },
+          ],
+        },
+      ],
+      // Block raw query-runner / repository calls even if a pool were obtained.
+      'no-restricted-syntax': [
+        'error',
+        {
+          selector:
+            "CallExpression[callee.property.name='createQueryRunner']",
+          message: 'Wall: no QueryRunner in features — use the RecordEngine (@astram/engine).',
+        },
+        {
+          selector:
+            "CallExpression[callee.property.name='getRepository']",
+          message: 'Wall: no repository access in features — use the RecordEngine (@astram/engine).',
+        },
+        {
+          selector:
+            "CallExpression[callee.property.name='createPool']",
+          message: 'Wall: features never create a DB pool — use the RecordEngine (@astram/engine).',
+        },
+      ],
+    },
+  },
+);

package/template/server/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "__APP_NAME__",
+  "version": "0.0.0",
+  "private": true,
+  "description": "The server (API) half of an Astram consumer app. Depends on the immutable framework (@astram/core, @astram/guard, @astram/engine, @astram/sdk) and declares enforcement via ShieldModule.forRoot(). Features go in src/features/; the UI lives in ../frontend.",
+  "type": "commonjs",
+  "main": "dist/main.js",
+  "scripts": {
+    "prebuild": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "tsc -p tsconfig.build.json",
+    "start": "node --env-file-if-exists=.env dist/main.js",
+    "dev": "node scripts/dev.mjs",
+    "test": "vitest run",
+    "lint": "eslint \"src/**/*.ts\" \"test/**/*.ts\"",
+    "guide:sync": "node scripts/sync-astram-guide.mjs",
+    "postinstall": "node scripts/sync-astram-guide.mjs"
+  },
+  "dependencies": {
+    "@astram/core": "^1.0.0",
+    "@astram/engine": "^0.1.0",
+    "@astram/guard": "^0.3.0",
+    "@astram/guide": "^0.1.0",
+    "@astram/identity": "^0.1.0",
+    "@astram/migrate": "^0.1.0",
+    "@astram/sdk": "^0.2.0",
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/core": "^11.0.0",
+    "@nestjs/platform-express": "^11.0.0",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "@nestjs/testing": "^11.0.0",
+    "@types/express": "^5.0.0",
+    "@types/node": "^22.0.0",
+    "@types/supertest": "^6.0.2",
+    "eslint": "^9.0.0",
+    "supertest": "^7.0.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.0",
+    "typescript-eslint": "^8.0.0",
+    "unplugin-swc": "^1.5.1",
+    "vitest": "^2.1.8"
+  }
+}

package/template/server/scripts/dev.mjs

@@ -0,0 +1,51 @@
+/**
+ * Dev runner — TypeScript watch + auto-restart, with CORRECT NestJS decorator
+ * metadata.
+ *
+ * WHY not `tsx watch`: tsx uses esbuild, which does NOT emit `emitDecoratorMetadata`.
+ * NestJS constructor injection (`constructor(private x: Service)`) depends on that
+ * metadata, so under tsx a controller's injected service is `undefined` at runtime
+ * (a silent 500 on the first call). `tsc` DOES emit the metadata — so this runner
+ * compiles with `tsc --watch` (→ dist/) and runs `node --watch dist/main.js`, giving
+ * hot-reload AND correct DI. Same compiler as the production build, no extra deps.
+ *
+ * `.env` is loaded by the node child via --env-file-if-exists.
+ */
+
+import { spawn } from 'node:child_process';
+import { existsSync, mkdirSync } from 'node:fs';
+
+mkdirSync('dist', { recursive: true });
+
+// 1) tsc in watch mode → dist/ (emits decorator metadata; the whole point).
+const tsc = spawn(
+  process.execPath,
+  [new URL('../node_modules/typescript/bin/tsc', import.meta.url).pathname, '-w', '-p', 'tsconfig.build.json', '--preserveWatchOutput'],
+  { stdio: 'inherit' },
+);
+
+// 2) Wait for the first emit, then run node --watch on the built entry.
+let started = false;
+const startNode = () => {
+  if (started) return;
+  if (!existsSync('dist/main.js')) {
+    setTimeout(startNode, 300);
+    return;
+  }
+  started = true;
+  const node = spawn(
+    process.execPath,
+    ['--env-file-if-exists=.env', '--watch', 'dist/main.js'],
+    { stdio: 'inherit' },
+  );
+  node.on('exit', (code) => {
+    tsc.kill();
+    process.exit(code ?? 0);
+  });
+};
+setTimeout(startNode, 800);
+
+process.on('SIGINT', () => {
+  tsc.kill();
+  process.exit(0);
+});

package/template/server/scripts/sync-astram-guide.mjs

@@ -0,0 +1,63 @@
+/**
+ * sync-astram-guide — copy the framework's guide docs into `.claude/rules/` so
+ * Claude Code reads the CURRENT framework rules.
+ *
+ * WHY (ADR-0025, the two-layer AI guide): the framework ships its hard rules +
+ * capabilities in the installed `@astram/guide` package (in node_modules). Claude
+ * Code reliably reads rules from `.claude/rules/` (a documented, symlink-aware
+ * location) — but NOT from an @import that points into node_modules. So this script
+ * bridges the two: it copies the framework docs from the installed package into the
+ * app-root `.claude/rules/`, where the app's CLAUDE.md references them.
+ *
+ * It runs on `npm install` AND `npm update` (wired as a postinstall in
+ * server/package.json), so a FRAMEWORK UPGRADE automatically refreshes the rules —
+ * the whole point of the upgrade-safe design. The copied files are GITIGNORED (they
+ * are a generated mirror of the framework's version); the developer-owned
+ * `.astram/guide/` layer is separate, git-tracked, and NEVER touched by this script.
+ *
+ * The app root is the monorepo root (one level up from server/), because CLAUDE.md +
+ * .claude/ live at the app root and Claude walks UP the tree from wherever you work.
+ */
+
+import { cpSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const here = dirname(fileURLToPath(import.meta.url)); // server/scripts
+const appRoot = resolve(here, '..', '..'); // monorepo root
+const rulesDir = join(appRoot, '.claude', 'rules');
+
+function main() {
+  let guide;
+  try {
+    guide = require('@astram/guide');
+  } catch {
+    // The framework guide package isn't installed (e.g. a partial install). Skip
+    // silently — this is a best-effort refresh, never a hard failure of the install.
+    process.stdout.write('[sync-astram-guide] @astram/guide not found — skipped.\n');
+    return 0;
+  }
+
+  mkdirSync(rulesDir, { recursive: true });
+  // Copy the framework docs into .claude/rules/ (overwrite — they are the framework's
+  // to own; on upgrade the newer versions replace the older ones cleanly).
+  cpSync(guide.FRAMEWORK_RULES_PATH, join(rulesDir, 'astram-framework-rules.md'));
+  cpSync(guide.CAPABILITIES_PATH, join(rulesDir, 'astram-framework-capabilities.md'));
+
+  // Stamp the synced version so a human/AI can see which framework version's rules
+  // are present (and notice when an upgrade changed them).
+  writeFileSync(
+    join(rulesDir, '.astram-guide-version'),
+    `${guide.version}\n`,
+    'utf8',
+  );
+
+  process.stdout.write(
+    `[sync-astram-guide] framework rules synced (v${guide.version}) → .claude/rules/\n`,
+  );
+  return 0;
+}
+
+process.exitCode = main();

package/template/package.json

@@ -1,37 +0,0 @@
-{
-  "name": "__APP_NAME__",
-  "version": "0.0.0",
-  "private": true,
-  "description": "An Astram consumer app. Depends on the published, immutable framework (@astram/core, @astram/guard, @astram/sdk) and declares enforcement via ShieldModule.forRoot(). Features go in src/features/.",
-  "type": "commonjs",
-  "main": "dist/main.js",
-  "scripts": {
-    "prebuild": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
-    "build": "tsc -p tsconfig.build.json",
-    "start": "node dist/main.js",
-    "dev": "tsx watch src/main.ts",
-    "test": "vitest run",
-    "lint": "eslint \"src/**/*.ts\" \"test/**/*.ts\""
-  },
-  "dependencies": {
-    "@astram/core": "^0.1.0",
-    "@astram/guard": "^0.1.1",
-    "@astram/sdk": "^0.1.0",
-    "@nestjs/common": "^11.0.0",
-    "@nestjs/core": "^11.0.0",
-    "@nestjs/platform-express": "^11.0.0",
-    "reflect-metadata": "^0.2.2",
-    "rxjs": "^7.8.1"
-  },
-  "devDependencies": {
-    "@nestjs/testing": "^11.0.0",
-    "@types/express": "^5.0.0",
-    "@types/node": "^22.0.0",
-    "@types/supertest": "^6.0.2",
-    "supertest": "^7.0.0",
-    "tsx": "^4.19.2",
-    "typescript": "^5.7.0",
-    "unplugin-swc": "^1.5.1",
-    "vitest": "^2.1.8"
-  }
-}