@codenotch/codenotch.cli 1.0.41 → 1.0.42

package/dist/utils/TemplateUtils.js

@@ -106,22 +106,112 @@ class TemplateUtils {
      * Folders of a new project, relative to its root
      */
     static PROJECT_FOLDERS = ['processes', 'apps', 'documents', 'tables'];
+    /**
+     * tsconfig.json of a Codenotch project.
+     *
+     * Its 'include' must cover the generated 'db-schema.d.ts': the declaration merging it carries
+     * only applies to files of the same TypeScript program, and without a tsconfig the editor
+     * builds an inferred program out of the open files alone, so a d.ts nobody imports would
+     * never be loaded and `ctx.tables` would stay untyped.
+     *
+     * '**' takes the whole workspace, so a folder the developer adds is typed like the rest. A
+     * wildcard never walks into 'node_modules' nor into a folder whose name starts with a dot
+     * ('.codenotch', '.git', '.vscode', ...), so only the rest has to be listed in 'exclude' -
+     * they are named there anyway, as the cli also reads it to know what not to package.
+     * 'compiled' holds the process bundles of 'cn project compile': generated .js that would
+     * otherwise join the program through allowJs.
+     */
+    static createTsConfigJson() {
+        return JSON.stringify({
+            compilerOptions: BuildUtils_1.default.defaultCompilerOptions(),
+            include: ['**/*'],
+            exclude: ['node_modules', '.codenotch', 'compiled']
+        }, null, 4) + '\n';
+    }
     static createGitignore() {
         return [
             'package-lock.json',
             '',
             '# Generated by the cli, regenerate them with the commands of the readme',
             // Anchored with a leading slash: these three only ever sit at the root of the project
-            '/db-schema.ts',
+            '/db-schema.d.ts',
             '/db-schema.xml',
             '/openapi.json',
             // No slash: a translation file can sit anywhere, and its class is generated next to it
             '*.i18n.ts',
+            // Process bundles of 'cn project compile'
+            '/compiled',
             '',
             '/.codenotch',
             '/node_modules'
         ].join('\n') + '\n';
     }
+    /**
+     * AGENTS.md of a new project: the entry point of AI coding agents (Claude Code reads it
+     * through CLAUDE.md). Kept short on purpose: the reference documentation ships with the CLI
+     * and is read through 'cn docs <topic>', so it follows the installed CLI instead of being
+     * frozen at the version that created the project.
+     */
+    static createAgentsMd(projectName, serviceName) {
+        return `# Instructions for AI coding agents
+
+This is **${projectName}**, a [Codenotch](https://codenotch.com/) project: TypeScript end to
+end, built and deployed on a Codenotch runtime by the \`cn\` CLI (\`npm install -g @codenotch/codenotch.cli\`).
+The website is not up to date — trust \`cn docs\` and the files of this project over it.
+Its service name is \`${serviceName}\` (see \`manifest.json\`): it identifies the project on the
+runtime and is part of its URL — never rename it on your own.
+
+## The reference documentation lives in the CLI
+
+Run \`cn docs\` to list the topics, and **read the topic before writing a file of that kind** —
+this file does not repeat the reference, and the docs follow the installed CLI version:
+
+| Command | Read before touching |
+| --- | --- |
+| \`cn docs project\` | anything — anatomy, manifest, generated files, lifecycle |
+| \`cn docs tables\` | \`tables/*.ts\`, \`documents/*.ts\` (\`defineEntity\`, \`defineDocument\`) |
+| \`cn docs processes\` | \`processes/*.ts\` (\`process({...})\` declarations) |
+| \`cn docs queries\` | \`queries/*.cnql\` |
+| \`cn docs apps\` | \`apps/*.tsx\` and their manifests |
+| \`cn docs i18n\` | \`*.i18n.csv\` |
+
+## Rules
+
+1. **Never edit generated files**: \`db-schema.xml\`, \`db-schema.d.ts\`, \`openapi.json\`,
+   \`*.i18n.ts\`, \`compiled/\`, \`.codenotch/\`. Fix the source they are generated from, then
+   regenerate.
+2. **Regenerate after changing sources** — tables or documents:
+   \`cn generate dbcontext -f .\`; processes exposing endpoints: \`cn generate openapi -f .\`;
+   translations: \`cn generate i18n -f <file>.i18n.csv\`.
+3. **Keep the TODO policy**: where the runtime API is not settled yet (the client-side call of a
+   process, the CNQL filter syntax), the sources carry an explicit \`TODO\` comment instead of a
+   guess. Never invent those APIs; carry the TODO and tell the user.
+4. **Check your work**: \`cn validate .\` reports hints, warnings and errors of every file, and
+   \`cn project compile\` typechecks and bundles the processes without deploying anything.
+   \`cn validate\`, \`cn project inspect\`, \`cn runtime info\` and \`cn docs\` take \`--json\`
+   for machine-readable output.
+
+## Everyday commands
+
+| Command | What it does |
+| --- | --- |
+| \`cn project start\` | build, deploy and start the project on the local runtime |
+| \`cn project refresh\` | after a change: sync the project with the running runtime |
+| \`cn project inspect\` | parse the project and display everything the CLI discovered |
+| \`cn project test\` | run the tests of the project |
+| \`cn react dev [app]\` | Vite dev server with HMR for one app |
+| \`cn runtime start\` / \`cn runtime info\` | start the local runtime / its status |
+
+Run \`cn --help\` (or \`cn <command> --help\`) for the complete list.
+`;
+    }
+    /**
+     * CLAUDE.md of a new project: Claude Code reads this file, the '@' import pulls the shared
+     * AGENTS.md in so both stay one single source of truth
+     */
+    static createClaudeMd() {
+        return `@AGENTS.md\n`;
+    }
     /**
      * readme.md of a new project: what the generated files are and how to work with them
      */
@@ -138,7 +228,7 @@ Renaming it later means updating every reference to it, so it is better chosen o
 ## Requirements
 
 ${fence}sh
-npm install -g codenotch-cli   # the 'cn' command
+npm install -g @codenotch/codenotch.cli   # the 'cn' command
 cn runtime update              # install (or update) the local Codenotch runtime
 ${fence}
 
@@ -154,7 +244,7 @@ The files the cli derives from the sources are not versioned (see \`.gitignore\`
 fresh clone they have to be written again before the project compiles:
 
 ${fence}sh
-cn generate dbcontext -f .            # db-schema.xml + db-schema.ts, when the project has tables
+cn generate dbcontext -f .            # db-schema.xml + db-schema.d.ts, when the project has tables or documents
 cn generate openapi -f .              # openapi.json, when processes expose endpoints
 cn generate i18n -f <file>.i18n.csv   # the typed class of each translation file
 ${fence}
@@ -171,11 +261,13 @@ ${fence}
 | --- | --- |
 | \`manifest.json\` | project name, service name, version, languages and roles |
 | \`package.json\` | npm dependencies, React and \`@codenotch/codenotch.react\` |
+| \`tsconfig.json\` | covers the sources and the generated \`db-schema.d.ts\`, which types \`ctx.tables\` |
 | \`processes/\` | server side processes, one TypeScript file each |
 | \`tables/\` | SQL table definitions |
 | \`documents/\` | NoSQL document schemas |
 | \`apps/\` | React apps: \`<App>.tsx\` and its \`<App>.manifest.json\` |
 | \`*.i18n.csv\` | translations, one column per language |
+| \`AGENTS.md\` | instructions for AI coding agents (\`CLAUDE.md\` imports it) |
 
 ## Apps
 

package/dist/utils/TemplateUtils.js.map

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

package/package.json

@@ -1,71 +1,78 @@
-{
-  "name": "@codenotch/codenotch.cli",
-  "version": "1.0.41",
-  "description": "A CLI tool for code management",
-  "main": "dist/index.js",
-  "files": [
-    "dist"
-  ],
-  "bin": {
-    "codenotch-cli": "./dist/bin/cli.js",
-    "cn": "./dist/bin/cli.js"
-  },
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsx src/index.ts",
-    "start": "node dist/index.js",
-    "clean": "rimraf dist",
-    "prebuild": "npm run clean",
-    "prepare": "npm run build",
-    "pack:check": "npm pack --dry-run",
-    "release": "npm run build && npm run pack:check && npm publish",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage"
-  },
-  "keywords": [
-    "cli",
-    "tool",
-    "code"
-  ],
-  "author": "Codenotch SA",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/EchinoHub/codenotch-cli.git"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "dependencies": {
-    "@codenotch/codenotch.core": "1.0.25",
-    "@octokit/auth-oauth-device": "^8.0.3",
-    "@types/express": "^5.0.6",
-    "adm-zip": "^0.5.17",
-    "chalk": "^5.3.0",
-    "commander": "^12.0.0",
-    "cross-keychain": "^1.1.0",
-    "decompress": "^4.2.1",
-    "dotenv": "^17.4.2",
-    "ignore": "^7.0.6",
-    "express": "^5.2.1",
-    "fs-extra": "^10.0.0",
-    "js2xmlparser": "^5.0.0",
-    "node-fetch": "^3.3.2",
-    "papaparse": "^5.3.1",
-    "typescript": "^5.9.3"
-  },
-  "devDependencies": {
-    "@types/adm-zip": "^0.5.8",
-    "@types/decompress": "^4.2.7",
-    "@types/fs-extra": "^9.0.13",
-    "@types/json-schema": "^7.0.6",
-    "@types/node": "^20.19.34",
-    "@types/papaparse": "^5.3.1",
-    "@vitest/coverage-v8": "^4.1.10",
-    "rimraf": "^5.0.0",
-    "ts-node": "^10.9.2",
-    "tsx": "^4.21.0",
-    "vitest": "^4.1.10"
-  }
-}
+{
+  "name": "@codenotch/codenotch.cli",
+  "version": "1.0.42",
+  "description": "The Codenotch CLI ('cn'): scaffold, run, validate, package and deploy full-stack TypeScript Codenotch projects - processes, tables, documents and React apps - on a local Codenotch runtime",
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "resources"
+  ],
+  "bin": {
+    "codenotch-cli": "./dist/bin/cli.js",
+    "cn": "./dist/bin/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "clean": "rimraf dist",
+    "prebuild": "npm run clean",
+    "prepare": "npm run build",
+    "pack:check": "npm pack --dry-run",
+    "release": "npm run build && npm run pack:check && npm publish",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "keywords": [
+    "codenotch",
+    "cn",
+    "cli",
+    "fullstack",
+    "typescript",
+    "react",
+    "scaffold",
+    "runtime"
+  ],
+  "author": "Codenotch SA",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/EchinoHub/codenotch-cli.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@codenotch/codenotch.core": "1.0.25",
+    "@octokit/auth-oauth-device": "^8.0.3",
+    "@types/express": "^5.0.6",
+    "adm-zip": "^0.5.17",
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "cross-keychain": "^1.1.0",
+    "decompress": "^4.2.1",
+    "dotenv": "^17.4.2",
+    "esbuild": "0.28.2",
+    "express": "^5.2.1",
+    "fs-extra": "^10.0.0",
+    "ignore": "^7.0.6",
+    "js2xmlparser": "^5.0.0",
+    "node-fetch": "^3.3.2",
+    "papaparse": "^5.3.1",
+    "typescript": "^5.9.3"
+  },
+  "devDependencies": {
+    "@types/adm-zip": "^0.5.8",
+    "@types/decompress": "^4.2.7",
+    "@types/fs-extra": "^9.0.13",
+    "@types/json-schema": "^7.0.6",
+    "@types/node": "^20.19.34",
+    "@types/papaparse": "^5.3.1",
+    "@vitest/coverage-v8": "^4.1.10",
+    "rimraf": "^5.0.0",
+    "ts-node": "^10.9.2",
+    "tsx": "^4.21.0",
+    "vitest": "^4.1.10"
+  }
+}

package/resources/docs/apps.md

@@ -0,0 +1,109 @@
+# React apps
+
+How the React apps of a project are structured, the `useCodenotch()` runtime bridge, styling with Scss or Tailwind, and the `cn react` commands.
+
+## An app is a pair of files
+
+An app is a `<Name>.tsx` and its sibling `<Name>.manifest.json`, both under `apps/`. The name
+must be a valid JavaScript identifier — it is also the React component name and how the
+`cn react` commands address the app. The `.tsx` default-exports the component:
+
+```tsx
+import React from 'react';
+import { useCodenotch } from '@codenotch/codenotch.react';
+
+const index: React.FC<{}> = () => {
+	const cn = useCodenotch();
+	return <div>
+		<h1>My new Codenotch App</h1>
+		<pre>{JSON.stringify(cn.env, null, 4)}</pre>
+	</div>;
+};
+
+export default index;
+```
+
+The manifest carries the display and PWA settings:
+
+```json
+{
+    "app": { "name": "index" },
+    "html": { "title": "My Project" },
+    "pwa": {
+        "name": "index",
+        "display": "standalone",
+        "display_override": ["window-controls-overlay"],
+        "start_url": "./",
+        "icons": [
+            { "src": "logo512.png", "sizes": "512x512", "type": "image/png" },
+            { "src": "logo192.png", "sizes": "192x192", "type": "image/png" }
+        ]
+    }
+}
+```
+
+`cn generate app -n <Name>` scaffolds the pair.
+
+## Stack
+
+- **React 19** — the only supported major.
+- **react-router 7** for multi-page apps, with `HashRouter`: it keeps the routing client side
+  whatever URL the runtime serves the app from.
+- **`@codenotch/codenotch.react`** — the bridge to the runtime, through `useCodenotch()`.
+
+## useCodenotch()
+
+What the generated code relies on:
+
+| Member | Meaning |
+| --- | --- |
+| `cn.env` | the environment the runtime gave the app |
+| `cn.getTheme()` / `cn.setTheme('light' \| 'dark')` | theme; `setTheme` toggles the `dark` class on `<html>` |
+| `cn.getLanguage()` / `cn.setLanguage(lang)` / `cn.getLanguages()` | languages, from `manifest.json` |
+| `cn.startProcess(processId, input)` | call a server-side process — **not implemented yet** in `@codenotch/codenotch.react` 2.0.1 (it throws `Not implemented.`) |
+
+For the full surface, read the typings in
+`node_modules/@codenotch/codenotch.react/dist/`. Because `startProcess` is not settled, generated
+projects wrap it in one typed `apps/api.ts` module carrying a `TODO` comment — keep that pattern
+instead of scattering direct calls.
+
+## Styling
+
+Every template styles through a `.scss` imported by the app entry (`import './index.scss'`).
+The Tailwind flavour uses **Tailwind CSS 4**:
+
+```scss
+// @use rather than @import: sass deprecates @import (gone in dart sass 3)
+@use "tailwindcss";
+
+/* setTheme('dark') toggles the 'dark' class on <html>: key the dark: variants on it */
+@custom-variant dark (&:where(.dark, .dark *));
+```
+
+plus a `postcss.config.js` with the `@tailwindcss/postcss` plugin, picked up by the Vite build.
+No CSS modules.
+
+## Translations in the UI
+
+Import the class generated from a `*.i18n.csv` and follow the runtime language (see
+`cn docs i18n`):
+
+```tsx
+import globals from '../../globals.i18n';
+
+globals.setLanguage(cn.getLanguage() ?? 'en');
+<h1>{globals.appTitle()}</h1>
+```
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `cn react dev [app]` | Vite dev server with HMR on the real project sources |
+| `cn react build [app]` | production bundle (options for a static or PWA build) |
+| `cn react serve [target]` | serve a build locally |
+| `cn react clean [app]` | delete the build staging of the app |
+| `cn react package [app]` | desktop installer (Tauri) |
+
+Apps are addressed by the `app.name` of their manifest; with a single app the name can be
+omitted.

package/resources/docs/i18n.md

@@ -0,0 +1,51 @@
+# Translations
+
+The `*.i18n.csv` translation files, and the typed class `cn generate i18n` derives from each of them.
+
+## The csv
+
+A `*.i18n.csv` holds one `key` column plus one column per language, matching the `languages` of
+`manifest.json`:
+
+```csv
+key,en,de,fr
+appTitle,My todo lists,Meine Aufgabenlisten,Mes listes de tâches
+todoCount,"{0} todo(s), {1} done","{0} Aufgabe(n), {1} erledigt","{0} tâche(s), {1} terminée(s)"
+```
+
+- `{0}`, `{1}`, ... are the placeholders of the arguments.
+- Standard CSV quoting: wrap a value containing a comma, a quote or a newline in double quotes.
+- Rows without a key are ignored (a leading empty row after the header is tolerated).
+- Best practice: one global file at the project root (e.g. `globals.i18n.csv`) rather than many
+  scattered ones.
+
+Keys should be valid identifiers (they become method names): a key that is not is converted with
+a warning, and the names `values`, `lang`, `setLanguage`, `getValue` are reserved.
+
+## The generated class
+
+```sh
+cn generate i18n -f globals.i18n.csv
+```
+
+writes `globals.i18n.ts` next to the csv — generated, gitignored, never edit it; regenerate after
+every change to the csv. The class name comes from the file name, and it exposes one static
+method per key:
+
+```tsx
+import globals from './globals.i18n';
+
+globals.setLanguage('de');
+globals.appTitle();                 // 'Meine Aufgabenlisten'
+globals.todoCount('3', '1');        // '3 Aufgabe(n), 1 erledigt'
+```
+
+Behavior of the generated methods:
+
+- the argument count of a method is the highest `{n}` placeholder across all languages, plus one;
+- a language without a value falls back to the first language column of the csv;
+- an unknown key returns `KEY '<key>' NOT EXISTS` rather than throwing — a visible marker in the
+  UI instead of a crash.
+
+In an app, follow the runtime language: `globals.setLanguage(cn.getLanguage() ?? 'en')` (see
+`cn docs apps`).

package/resources/docs/processes.md

@@ -0,0 +1,87 @@
+# Processes
+
+How to write the server-side processes of a project with `@codenotch/process`, what `ctx` offers, and the constraints coming from how they are bundled and executed.
+
+## Declaring a process
+
+A process is a `process({...})` declaration, conventionally grouped by domain in files under
+`processes/`:
+
+```ts
+import { process, api, Context } from '@codenotch/process'
+import type { ITodoList } from '../tables/todolist'
+
+export const createTodoList = process({
+  id: 'CreateTodoList',
+  description: 'Creates an empty todo list',
+  auth: { scope: 'internal' },
+  trigger: api.post('/todolists'),
+  run: async (ctx: Context, input: { name: string }): Promise<{ id: string }> => {
+    const id = ctx.uuid()
+    await ctx.tables.todolists.write(id, { name: input.name })
+    return { id }
+  },
+})
+```
+
+| Property | Meaning |
+| --- | --- |
+| `id` | Unique across the project, a **string literal**. The registry key and the `ctx.call` target. |
+| `description` | One line, shown in diagnostics and OpenAPI. |
+| `auth.scope` | Who may start it: `'public'`, `'internal'`, `'system'`. |
+| `trigger` | How it starts (below). Omitted: only reachable through `ctx.call` from another process. |
+| `run` | `async (ctx, input) => output`. Always returns a Promise. |
+
+Triggers:
+
+| Trigger | Starts the process |
+| --- | --- |
+| `api.get('/route')` / `api.post` / `api.put` / `api.delete` | as an HTTP endpoint; `:param` segments land in `input` |
+| `timer('0 7 * * *')` | on a cron schedule |
+| `signal('some.ref')` | when that signal is raised |
+| `install({ ... })` | at installation of the project |
+
+Type the `input` parameter and the return type of `run`: the CLI turns those annotations into
+JSON schemas used for payload validation and `openapi.json` (`cn generate openapi -f .`).
+
+## What `ctx` offers
+
+The capabilities the generated code relies on:
+
+| Member | Meaning |
+| --- | --- |
+| `ctx.tables.<collection>.write(id, patch)` | insert or update a row (only the fields present in the patch are written) |
+| `ctx.tables.<collection>.require(id)` | one row, throws when the id is unknown — an `api` process turns that into a 404 |
+| `ctx.tables.<collection>.delete(id)` | delete a row (relations with `linkBehaviour('Delete')` cascade) |
+| `ctx.query<T>('queries/x.cnql', params)` | run a read query, see `cn docs queries` |
+| `ctx.uuid()` | a new UUID |
+| `ctx.call` | start another process by its `id` |
+| `ctx.log.info(message, data)` | structured logging |
+
+`ctx.tables` is typed by the generated `db-schema.d.ts` — regenerate it after changing a table
+(`cn generate dbcontext -f .`), otherwise the collections stay untyped.
+
+## Rules — a process that breaks them is skipped with a warning, never guessed
+
+- **Export the variable** (`export const createTodoList = ...`): a non-exported process is not
+  reachable.
+- **Literal, unique `id`**: an id that is missing, computed at runtime, or already used by
+  another process gets the declaration skipped.
+
+## Bundling constraints
+
+At packaging time each process becomes one self-contained `.js` artifact executed in a bare V8
+engine — no Node, no module system. Consequences for the code you write:
+
+- **No Node standard library** (`fs`, `node:crypto`, ...): importing one is a compile error, it
+  cannot exist in the runtime's engine.
+- **npm dependencies are inlined** into each artifact: only pure-JS packages can work (no native
+  addons, no Node API inside).
+- `@codenotch/*` packages are **provided by the runtime**, never inlined.
+- **Module-level state is per process**: a top-level cache in a shared helper exists once per
+  artifact, it is never shared between processes.
+- The whole project is **typechecked before bundling**: type errors fail the packaging.
+
+`cn project compile` runs the same typecheck and bundling without packaging — the quick way to
+check the processes build. `cn generate process` scaffolds boilerplate processes (CRUD, api) for
+a discovered table (`-m api|insert|insert-full|update|upsert|delete|clean`).

package/resources/docs/project.md

@@ -0,0 +1,101 @@
+# The anatomy of a Codenotch project
+
+What a Codenotch project is made of, which files are generated from which sources, and the commands of its lifecycle.
+
+A Codenotch project is TypeScript end to end: server-side processes are `process({...})`
+declarations from `@codenotch/process`, tables are `defineEntity({...})` from `@codenotch/orm`,
+apps are React 19 components. The project is built, deployed and run on a Codenotch runtime by
+the `cn` CLI. The CLI discovers what the project declares by parsing its TypeScript sources —
+there is no registry to maintain by hand.
+
+## Layout
+
+| Path | Contains | Topic |
+| --- | --- | --- |
+| `manifest.json` | project name, service name, version, languages and roles | below |
+| `package.json` | npm dependencies, React and `@codenotch/codenotch.react` | |
+| `tsconfig.json` | covers the sources and the generated `db-schema.d.ts` | below |
+| `processes/` | server side processes, plain TypeScript files | `cn docs processes` |
+| `tables/` | SQL table definitions (`defineEntity`) | `cn docs tables` |
+| `documents/` | NoSQL document schemas (`defineDocument`) | `cn docs tables` |
+| `queries/` | `.cnql` read queries run by the processes | `cn docs queries` |
+| `apps/` | React apps: `<App>.tsx` and its `<App>.manifest.json` | `cn docs apps` |
+| `*.i18n.csv` | translations, one column per language | `cn docs i18n` |
+
+The folder names are a convention, not a requirement: the CLI discovers declarations by parsing
+every TypeScript file of the project, wherever it sits.
+
+## manifest.json
+
+```json
+{
+    "packages": {},
+    "projectName": "My Project",
+    "serviceName": "myproject",
+    "languages": ["en", "de", "fr"],
+    "roles": [],
+    "version": "0.0.0",
+    "dependencies": [],
+    "postInstallationProcesses": []
+}
+```
+
+`serviceName` identifies the project on the runtime and is part of its URL. Renaming it means
+updating every reference to it (queries carry it as their `xmlns`, for instance) — treat it as
+fixed unless the user explicitly asks for a rename.
+
+## Generated files — never edit them
+
+| File | Generated from | Regenerate with |
+| --- | --- | --- |
+| `db-schema.xml` | the `defineEntity` declarations | `cn generate dbcontext -f .` |
+| `db-schema.d.ts` | same — types `ctx.tables` by declaration merging | `cn generate dbcontext -f .` |
+| `openapi.json` | the processes exposing endpoints | `cn generate openapi -f .` |
+| `*.i18n.ts` | its sibling `*.i18n.csv` | `cn generate i18n -f <file>.i18n.csv` |
+| `compiled/` | the processes, one self-contained `.js` each | `cn project compile` (or packaging) |
+| `.codenotch/` | React build staging | `cn react build` |
+
+These files are in `.gitignore`: after a fresh clone they have to be generated again before the
+project compiles. When one of them looks wrong, fix the source it is generated from, then
+regenerate — an edit to the generated file is overwritten on the next run.
+
+`tsconfig.json` must keep including `db-schema.d.ts`: the declaration merging it carries only
+applies to files of the same TypeScript program, so removing it from `include` silently untypes
+`ctx.tables` in every process.
+
+## Lifecycle
+
+```sh
+npm install -g @codenotch/codenotch.cli   # the 'cn' command
+cn runtime update              # install (or update) the local Codenotch runtime
+cn runtime start               # start it
+cn project start               # build, deploy and open this project
+cn project refresh             # after a change: sync the project with the runtime
+```
+
+Checks, at any time:
+
+```sh
+cn validate .                  # hints, warnings and errors of every file
+cn project inspect             # parse the project and display everything the CLI discovered
+cn project test                # run the tests of the project
+cn project compile             # typecheck and bundle the processes, without packaging
+```
+
+`cn validate`, `cn project inspect`, `cn runtime info` and `cn docs` all take `--json` for
+machine-readable output.
+
+Shipping:
+
+```sh
+cn project package             # compile and package the project as a zip
+cn project deploy <service> <zip>
+```
+
+Packaging typechecks the whole project first: type errors fail it.
+
+## The TODO policy
+
+Where the runtime API is not settled yet (the client-side call of a process, the CNQL filter
+syntax), the code carries an explicit `TODO` comment instead of a guess. Keep that policy: never
+invent an API shape where the existing sources marked one as unsettled.