@ofidj/generator-fidj 1.0.0 → 1.0.1

package/README.md

@@ -1,74 +1,109 @@
 # @ofidj/generator-fidj
 
-[![NPM version][npm-image]][npm-url]
-[![Build Status][travis-image]][travis-url]
+Generate a Fidj-integrated TypeScript app with a short command. Public identity and content are generator inputs; authentication and per-app privacy are reusable template behavior. Node 22 or 24 is the validation matrix.
 
-> build great mobile and web angular/ionic apps based on fidj.ovh authentication.
->
-> _Renamed from `generator-fidj` at 1.0.0. The old `generator-fidj@3.x` is deprecated. The yeoman command becomes `yo @ofidj/fidj` (note the `@ofidj/` prefix)._
+## Content app — static hosting
 
-## Prerequisites
+```sh
+create-fidj my-app --app-id YOUR_FIDJ_ID --title "My App" --welcome "Welcome" --content "<p>About my app</p>" --domain example.com
+cd my-app
+npm install && npm run build-prod
+```
 
-Look at mat's gist : https://gist.github.com/mlefree/2156f66dfb441f107bef157dde56a836
+Serve `www/` on a static host. It contains your public content, SDK sign-in/account creation, current roles, consent/history, scoped export and confirmed departure, plus `CNAME`. Private signing keys are never needed in the browser. `npm start` supplies an optional Node preview; this mode makes its API calls directly to Fidj.
 
-## Installation
+`--content` is trusted developer-authored HTML (like any checked-in application source), never untrusted visitor input. Set real terms before release; the generated agreement is explicitly a demo. The content app has no independent user database. Erasure/export cover Fidj-held membership records, and pending cleanup stays pending.
 
-First, install [Yeoman](http://yeoman.io) and generator-fidj using [npm](https://www.npmjs.com/) (we assume you have pre-installed [node.js](https://nodejs.org/)) :
-```bash
-npm install -g yo
-npm install -g @ionic/cli
-npm install -g @angular/cli
-npm install -g @ofidj/generator-fidj
-```
-Then generate your new project:
-```bash
-yo @ofidj/fidj
-```
-or as an expert :
-```bash
-yo @ofidj/fidj my-app app2021 your-app-id "" me-as-user "my description" \
-   "Welcome there" \
-   "Hey<br>Heres my content: <img src=blank /><br> \o/ "
-```
+## Backend example — protected actions
 
-## Development
+Omit `--content` to generate Studio Notes: a browser client plus Node backend with private persisted notes. The backend revalidates the session and live app roles for every protected request. Owner/Editor may write; other members may read their own notes. This mode requires Node hosting and is separate from the static content app scenario.
 
-Make sure you've got yeoman installed :
-```bash
-npm install -g yo
-npm install -g @ionic/cli
-npm install -g @angular/cli
-```
+Configure the generated privacy adapter so departure from either Studio Notes or Fidj erases the same app data. Notes persist outside disposable output. Failed cleanup stays pending in Fidj and can be retried; completed receipts remain visible. See the generated README for server-side configuration and persistence limits.
 
-Clone the repo, install it :
-```bash
-cd generator-fidj
-npm install
-npm link
-```
+## CLI and local development
+
+The package exposes `create-fidj`; from its checkout use `node bin/create-fidj.cjs`. Yeoman `yo @ofidj/fidj my-app --app-id YOUR_FIDJ_ID` invokes the same scaffolder and accepts the content/title/welcome/domain options. The old `app2021` positional command is a historical reference, not the maintained interface.
+
+- `--anonymous true|false`: show or hide anonymous entry in content apps (default: `true`). Set `--anonymous false` for a sign-in-only entry flow, as mleweb does.
+- `--api-endpoint`: select the API (default: hosted sandbox).
+- `--sdk-path` or `FIDJ_SDK_DIR`: use a built local SDK during coordinated development.
+- `--local` or `FIDJ_LOCAL=true`: use the loopback API/console. Test credentials stay in the validation guide, outside the content app UI. Supply the matching local app ID; `FIDJ_APP_ID` can override it.
+- `--replace`: regenerate only a destination containing `.fidj-generated`; unmarked projects are protected.
+
+Generation writes `.env.example`, `.env` and public `app.config.json`. Static configuration is embedded at build time: regenerate/rebuild when changing endpoints. Notes server configuration is read at runtime. Do not place secrets in any public configuration or content input.
+
+During this unreleased milestone, build `../fidj-node` and pass `--sdk-path ../fidj-node/dist`. Committed templates use registry dependency `@ofidj/node ^3.6.24`; a registry-only install is not validated until coordinated versions are published.
+
+## Real validation repository
+
+[mleweb](https://github.com/mlefree/mleweb) is the thin command-line validation fixture whose generated website is mlefree.com. Its `package.json` passes the original Mario GIF, welcome text and About/CV/contact links directly into this generator. No custom downstream renderer is required. GitHub CI runs the same generation/build path on Node 22/24 and uploads artifacts. Publishing the site to gh-pages, which is what mlefree.com serves, is a separate deliberate job: it runs on mleweb's `master` or on an explicit workflow dispatch, never from a version branch.
+
+Run `npm test` for scaffolding/CLI safety tests. Generated projects include TypeScript checking and HTTP integration tests for live authorization and privacy isolation. Local acceptance steps are in the workspace's `product-plan/09-generated-app-validation.md`.
+
+
+## Releasing to npm
+
+Pushing to the `package` branch publishes the package, the same convention the
+SDK and contracts repositories use. CI installs, runs the tests and publishes
+with `NPM_TOKEN`; this package publishes from the repository root rather than
+from a `dist` directory, because it ships its sources.
+
+The package contains `bin/`, `lib/` and the `typescript` template only. The
+`app2018` and `app2021` Yeoman templates are excluded: nothing reads them, and
+they accounted for 11.8MB of the 11.9MB published. `main` points at
+`lib/scaffold.cjs`, so `require('@ofidj/generator-fidj')` returns `{ scaffold }`
+alongside the `create-fidj` binary.
+
+Publish contracts before the SDK, and the SDK before anything that resolves it
+from the registry: the SDK depends on `@ofidj/contracts` by range, so a build
+picks up whatever is published at the time.
+
+## Entry flow
 
-And then use your local Fidj generator : 
-```bash
-mkdir your-app && cd your-app && \
-   yo @ofidj/fidj my-app app2021 your-app-id "" me-as-user "my description" \
-   "Welcome there" \
-   "Hey<br>Heres my content: <img src=blank /><br> \o/ " 
+The generated content app opens on `/#/signin`. Sign in, or choose **Enter anonymously** when enabled, to open `/#/content`, containing the supplied HTML. Signed-in users can open **My privacy** separately. Sign-out and departure return to the sign-in screen. Anonymous content is public; this navigation flow is not a security boundary for static assets.
 
-# look at the code : code .
-# or start it : npm start
+## Compose an existing app as a module
+
+Build your application for the `/module/` base URL, then pass its public output to the same generator:
+
+```sh
+create-fidj my-app --app-id YOUR_FIDJ_ID --title "My App" --welcome "Welcome back" --description "Your app description" --anonymous false --module ./built-console --module-entry 'index.html#/my'
+cd my-app && npm install && npm run build-prod
 ```
 
-## License
+The result is one static website: the generated SDK sign-in entry and the module under `www/module/`. After login, the entry opens the module on the same origin. The module must use the same public app ID/API and independently validate authorization for its own operations. The generator copies public build assets without changing their source; module input cannot contain environment files, dependency directories or symlinks.
+
+Hash routes other than the generated entry/content/privacy views are forwarded to the module, preserving existing public cards and console links. The module remains responsible for guarding private routes.
+
+The module entry receives a `meta[name="fidj-signin"]` URL, relative to its base URL. A module can send its sign-in, logout or expired-session flow there. Fidj's console implements this handoff and preserves departure status. The generated preview serves module assets from an explicit build manifest, including directory index URLs.
+
+`fidj-app` now exercises this path with `npm run create:local`: its owner/profile/privacy features remain an explicit Angular console module, while the generator owns the shared entry and final assembly. The local launcher serves the generated Fidj output on port 4200. The source console is maintained outside disposable `.gen` and must be rebuilt before regenerating.
+
+## Generated account lifecycle
+
+Content and module entries include `#/forgot`, `#/reset`, `#/verify`, and authenticated `#/account` screens in the same split layout as sign-in. These routes remain in the generated shell when an application module is attached. Forgot-password responses are neutral; verification requires an explicit click. `My account` provides verification status and resend. Password reset affects the shared Fidj identity across apps. Configure the API’s trusted account UI URL for email links; the current generated API integration requires the coordinated 3.6.24 SDK/API. The server-backed Notes template remains a separate integration example.
+
+## App data adapter
+
+The Notes server exposes `POST /fidj/privacy` for HMAC-authenticated, timestamped export/erase operations. Set a private `FIDJ_PRIVACY_ADAPTER_KEY` and register the same app ID, endpoint and key in the API’s server-side `FIDJ_PRIVACY_ADAPTERS`. Static content apps need no independent data adapter. `FIDJ_DATA_DIR` must stay outside `www`, `dist` and disposable generated output; the generated environment defaults to a sibling data directory.
+
+The file adapter uses atomic writes and a serialized queue for one writer process. Replace it with a transactional database for multi-instance hosting. Erasure receipts retain a hashed subject for replay protection, pruned after 30 days on the next write. Backups and unregistered stores are not covered. Tests exercise live authorization, restart persistence, private exports, adapter authentication, failed cleanup and duplicate-request safety.
+
+
+### Check a registered data handler
+
+Generated starters include `npm run privacy:check`: configure the server-only `FIDJ_PRIVACY_ADAPTER_KEY` in `.env`, start the app, then run the command. It signs a readiness request, verifies capabilities and probes durable storage without exporting or deleting user records. `FIDJ_APP_URL` can override the default loopback URL. `npm run privacy:rehearse` builds and exercises an isolated temporary data store, including scoped export, failure, retry and persistence. Production app data and credentials are never inputs to that rehearsal.
+
+Readiness confirms this handler only. Register its trusted URL and independent secret with the Fidj API operator; the app owner console can then check the same connection. Group roles granted in Fidj are enforced by the generated backend on each protected operation.
+
+## Generate an OIDC app
+
+`--oidc-issuer` switches the shared content/module entry to “Continue with Fidj”. The issuer owns password entry; the generator preserves your title, welcome message, logo/content inputs and anonymous-entry choice.
+
+```sh
+create-fidj my-app --app-id YOUR_APP_ID --api-endpoint https://api.sandbox.fidj.ovh/v3 --oidc-issuer https://api.sandbox.fidj.ovh/oidc --anonymous false --content '<h1>My app</h1>'
+```
 
-MIT 2021 © [fidj.ovh](fidj.ovh)
+An operator must enable that issuer before this command can authenticate. Register the exact deployed entry URL as the callback; it must not contain a fragment. Local loopback HTTP is supported. During the unreleased beta, use the coordinated SDK checkout through `--sdk-path`; registry-only publication is still pending.
 
-[npm-image]: https://badge.fury.io/js/@ofidj%2Fgenerator-fidj.svg
-[npm-url]: https://npmjs.org/package/@ofidj/generator-fidj
-[travis-image]: https://travis-ci.org/ofidj/generator-fidj.svg?branch=master
-[travis-url]: https://travis-ci.org/ofidj/generator-fidj
-[daviddm-image]: https://david-dm.org/ofidj/generator-fidj.svg?theme=shields.io
-[daviddm-url]: https://david-dm.org/ofidj/generator-fidj
-[coveralls-image]: https://coveralls.io/repos/ofidj/generator-fidj/badge.svg
-[coveralls-url]: https://coveralls.io/r/ofidj/generator-fidj
-[codecov-image]: https://codecov.io/gh/ofidj/generator-fidj/branch/master/graph/badge.svg
-[codecov-url]: https://codecov.io/gh/ofidj/generator-fidj
+OIDC currently supports static content and application-module assemblies. The Notes storage fixture retains its existing auth flow; no migration of stored Notes subjects is implied. Static HTML/assets remain public regardless of the login screen. Confidential data needs server authorization, preferably with an HttpOnly backend session. mleweb remains the command-line generator fixture: retain the original Mario and About/CV content, and activate OIDC only after its target issuer and callback are configured.

package/bin/create-fidj.cjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+const { parseArgs } = require("node:util");
+const { scaffold } = require("../lib/scaffold.cjs");
+try {
+  const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+      "app-id": { type: "string" },
+      "api-endpoint": { type: "string" },
+      "oidc-issuer": { type: "string" },
+      "sdk-path": { type: "string" },
+      title: { type: "string" },
+      welcome: { type: "string" },
+      description: { type: "string" },
+      content: { type: "string" },
+      anonymous: { type: "string" },
+      domain: { type: "string" },
+      module: { type: "string" },
+      "module-entry": { type: "string" },
+      local: { type: "boolean" },
+      replace: { type: "boolean" },
+      help: { type: "boolean" },
+    },
+  });
+  if (values.help || positionals.length !== 1) {
+    console.log(
+      "Usage: create-fidj <directory> --app-id <fidjId> [--api-endpoint <url>] [--title <text> --welcome <text> --description <text> --content <html> --domain <hostname>] [--module <built-directory> --module-entry <index.html#/route>] [--oidc-issuer https://api.example/oidc] [--anonymous true|false] [--local] [--replace]",
+    );
+    process.exitCode = values.help ? 0 : 1;
+  } else {
+    const dir = scaffold(positionals[0], {
+      appId: process.env.FIDJ_APP_ID || values["app-id"],
+      apiEndpoint: values["api-endpoint"],
+      oidcIssuer: values["oidc-issuer"],
+      sdkPath: values["sdk-path"] || process.env.FIDJ_SDK_DIR,
+      title: values.title,
+      welcome: values.welcome,
+      description: values.description,
+      content: values.content,
+      anonymous: values.anonymous,
+      domain: values.domain,
+      module: values.module,
+      moduleEntry: values["module-entry"],
+      local: values.local || process.env.FIDJ_LOCAL === "true",
+      replace: values.replace,
+    });
+    console.log(
+      `Created ${dir}\nNext: copy .env.example to .env, then npm install && npm run build && npm start.`,
+    );
+  }
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = 1;
+}

package/generators/app/index.js

@@ -1,200 +1,69 @@
-const Generator = require('yeoman-generator');
-const yosay = require('yosay');
-const chalk = require('chalk');
+const Generator = require("yeoman-generator");
+const { scaffold } = require("../../lib/scaffold.cjs");
 
 module.exports = class extends Generator {
   constructor(args, opts) {
     super(args, opts);
-
-    this.hasBeenRecordedInFidjOvh = true;
-    this.templateName = 'app2021'; //'app2021'; //'app2018' ''ionic2020'
-
-    this.option('skip-welcome-message', {
-      desc: 'Skips the welcome message',
-      type: Boolean
+    this.argument("appname", { type: String, required: false });
+    this.option("app-id", { type: String });
+    for (const key of [
+      "title",
+      "welcome",
+      "description",
+      "content",
+      "domain",
+      "sdk-path",
+      "anonymous",
+      "module",
+      "module-entry",
+    ])
+      this.option(key, { type: String });
+    this.option("api-endpoint", {
+      type: String,
+      default: "https://api.sandbox.fidj.ovh/v3",
     });
-
-    this.argument('appname', {type: String, required: false, desc: 'Your app name'});
-    this.argument('appType', {type: String, required: false, desc: 'For ex: "app2021" '});
-    this.argument('appId', {type: String, required: false});
-    this.argument('appOptions', {type: String, required: false});
-    this.argument('appUserName', {type: String, required: false});
-    this.argument('appDescription', {type: String, required: false});
-    this.argument('appWelcome', {type: String, required: false});
-    this.argument('appContent', {type: String, required: false});
-  }
-
-  async initializing() {
-    this.pkg = require('../../package.json');
   }
-
   async prompting() {
-    if (!this.options['skip-welcome-message'] && !this.options.appId) {
-      this.log(yosay('\'Allo \'Welcome to ' + chalk.red('fidj.ovh') + ' generator'));
-
-      const promptConditions = [{
-        type: 'confirm',
-        name: 'hasBeenRecordedInFidjOvh',
-        message: 'Did you recorded your app in fidj.ovh and received your appId ?',
-        default: false
-      }];
-
-      const conditions = await this.prompt(promptConditions);
-      this.hasBeenRecordedInFidjOvh = !!conditions.hasBeenRecordedInFidjOvh;
-      if (!this.hasBeenRecordedInFidjOvh) {
-        const err = 'You need to submit your app on https://fidj.ovh first. ' +
-          'It will help you to build a valid app name and give you a appId.';
-        this.log(yosay('Sorry : ' + chalk.red(err) + ' See you in 2 minutes ?'));
-      }
-    }
-
-    if (!this.options.appname || !this.options.appUserName || !this.options.appDescription) {
-      const prompts = [
-        {
-          type: 'input',
-          name: 'appUserName',
-          message: 'Your (github) user name'
-        },
-        {
-          type: 'input',
-          name: 'appName',
-          message: 'Your app name (as shown on device)',
-          default: this.appname.replace(/[^\w\s]/gi, '').replace(/\s/g, '_').replace(/\s+/g, '').replace(/[\. ,:-]+/g, '').toLowerCase()
-        },
-        {
-          type: 'input',
-          name: 'appDescription',
-          message: 'App description',
-          default: this.appname
-        }
-      ];
-
-      this.props = await this.prompt(prompts);
-    } else {
-      this.props = {
-        appName: this.options.appname,
-        appUserName: this.options.appUserName,
-        appDescription: this.options.appDescription,
-        appWelcome: this.options.appWelcome || '<h1>Welcome</h1>',
-        appContent: this.options.appContent || '<h1>Hello</h1>'
-      };
-    }
-
-    const pack = this.props.appUserName.replace(/[^\w\s]/gi, '').replace(/\s+/g, '').replace(/[\. ,:-]+/g, '').toLowerCase();
-    const age = this.props.appName.replace(/[^\w\s]/gi, '').replace(/\s/g, '_').replace(/\s+/g, '').replace(/[\. ,:-]+/g, '').toLowerCase();
-    const packageDefault = 'ovh.' + (pack ? pack : 'fidj') + '.' + age;
-
-    if (!this.options.appId) {
-      const prompts02 = [{
-        type: 'input',
-        name: 'appId',
-        message: 'Your app Id'
-      },
-        {
-          type: 'input',
-          name: 'appPackage',
-          message: 'Your app package name',
-          default: packageDefault
-        },
-        {
-          type: 'input',
-          name: 'appHomepage',
-          message: 'Home page url',
-          default: 'https://fidj.ovh/_/' + age
-        }
-      ];
-
-      this.props02 = await this.prompt(prompts02);
-    } else {
-      this.props02 = {
-        appId: this.options.appId,
-        appPackage: packageDefault,
-        appHomepage: 'https://fidj.ovh/_/' + age
-      };
-    }
+    this.answers = await this.prompt([
+      ...(!this.options.appname
+        ? [
+            {
+              type: "input",
+              name: "name",
+              message: "Project name",
+              default: "my-fidj-app",
+            },
+          ]
+        : []),
+      ...(!this.options["app-id"]
+        ? [
+            {
+              type: "input",
+              name: "appId",
+              message: "Public fidjId from your owner console",
+            },
+          ]
+        : []),
+    ]);
   }
-
-  async writing() {
-    if (!this.hasBeenRecordedInFidjOvh) {
-      return;
-    }
-
-    let copyAll = true;
-    if (this.options.appType === 'app2018') {
-      this.templateName = 'app2018';
-    } else {
-      this.templateName = 'app2021';
-    }
-
-    const now = new Date();
-    const version = '' + ('' + now.getFullYear()).substr(2) + '.' + (now.getMonth() + 1) + '.' + now.getDate();
-
-    const appArguments = {
-      appName: this.props.appName,
-      appNameStrict: this.props.appName.replace(/[^\w\s]/gi, '').replace(/\s+/g, '').replace(/[\. ,:-]+/g, '').toLowerCase(),
-      appDescription: this.props.appDescription,
-      appWelcome: this.props.appWelcome,
-      appContent: this.props.appContent,
-      appUserName: this.props.appUserName,
-      appHomepage: this.props02.appHomepage,
-      appPackage: this.props02.appPackage,
-      appId: this.props02.appId,
-      appOptions: this.options.appOptions ? ', {' + this.options.appOptions + '}' : '',
-      appVersion: version,
-      appKeywords: 'fidj',
-      appYear: now.getFullYear(),
-      appColor: 'white'
-    };
-
-    this.fs.copyTpl(
-      this.templatePath(this.templateName + '/*'),
-      this.destinationPath(),
-      appArguments
-    );
-
-    this.fs.copyTpl(
-      this.templatePath(this.templateName + '/.*'),
-      this.destinationPath(),
-      appArguments
-    );
-
-    this.fs.copyTpl(
-      this.templatePath(this.templateName + '/src'),
-      this.destinationPath('src'),
-      appArguments
+  writing() {
+    const name = this.options.appname || this.answers.name;
+    scaffold(this.destinationPath(name), {
+      name,
+      title: this.options.title,
+      welcome: this.options.welcome,
+      description: this.options.description,
+      content: this.options.content,
+      anonymous: this.options.anonymous,
+      module: this.options.module,
+      moduleEntry: this.options["module-entry"],
+      domain: this.options.domain,
+      sdkPath: this.options["sdk-path"],
+      appId: this.options["app-id"] || this.answers.appId,
+      apiEndpoint: this.options["api-endpoint"],
+    });
+    this.log(
+      `Created ${name}. Copy .env.example to .env, then npm install && npm run build && npm start.`,
     );
-
-    if (copyAll) {
-      this.fs.copy(
-        this.templatePath(this.templateName + '/platforms'),
-        this.destinationPath('platforms')
-      );
-
-      this.fs.copy(
-        this.templatePath(this.templateName + '/resources'),
-        this.destinationPath('resources')
-      );
-
-      this.fs.copy(
-        this.templatePath(this.templateName + '/tests'),
-        this.destinationPath('tests')
-      );
-
-      //this.fs.copy(
-      //  this.templatePath(this.templateName + '/www'),
-      //  this.destinationPath('www')
-      //);
-    }
-  }
-
-  async install() {
-    if (!this.hasBeenRecordedInFidjOvh) {
-      return;
-    }
-    this.npmInstall();
-  }
-
-  async end() {
-
   }
 };

package/generators/app/templates/typescript/README.md

@@ -0,0 +1,73 @@
+# Your Fidj TypeScript app
+
+A generated TypeScript client with Fidj sign-in and app-scoped privacy. The generator selects the mode from its inputs:
+
+- With `--content`: public HTML plus account/privacy controls, built to static `www/` assets and optional `CNAME`. No app backend is required; the client calls Fidj directly.
+- Without `--content`: Studio Notes, with a Node backend enforcing live Owner/Editor roles for private notes.
+
+The public title, welcome, HTML content and endpoints are in `app.config.json`. Edit the original generator command and regenerate for repeatable changes. Content HTML is trusted developer source.
+
+## Run
+
+Use Node 22 or later. Copy `.env.example` to `.env`, set the public app ID and Fidj API URL, then:
+
+```sh
+npm install
+npm run build
+npm start
+```
+
+Open http://localhost:8200. For content apps, `npm run build-prod` produces static `www/` assets; the Node process is only an optional preview. For Studio Notes, the backend must run for protected operations. Configure Fidj’s allowed origins for your app domain. No app signing key belongs in the browser or this starter’s public configuration.
+
+The current unreleased generator requires the matching `@ofidj/node` 3.6.24 SDK. Until publication, generate with `--sdk-path /absolute/path/to/fidj-node/dist` after building that SDK. Local file dependencies belong only in generated development output; use registry dependencies for release.
+
+## Structure
+
+- `src/content.ts`: static content app account, live roles and privacy controls.
+- `src/main.ts`: `FidjNodeService.init`, login, browser session and views.
+- `server/index.ts`: `verifyAppSession` on every protected request; live roles decide whether a note can be saved. Changing a role takes effect on the next backend request, even if a browser still displays old roles.
+- `test/server.test.mjs`: fresh HTTP servers verify role changes, revoked/foreign sessions, outage failure, per-user notes and privacy scope.
+- `scripts/build.mjs`: browser and Node builds using [esbuild](https://esbuild.github.io/getting-started/), with a separate TypeScript typecheck.
+
+Run `npm test` before changing the template. Every fresh generated app includes the same tests.
+
+## Privacy scope
+
+Optional preferences and their history belong to this app. In the static content app, export covers the Fidj-held membership records and no independent app database exists. In Studio Notes, export includes the Fidj membership and the starter’s notes. Leaving through this app removes its Fidj membership and locally held notes. App owners must resolve ownership first.
+
+Notes persist in `FIDJ_DATA_DIR`. With the adapter registered below, direct export/departure from Fidj includes these notes. Failed erasure keeps a request in Fidj for automatic retry with backoff; people can also retry explicitly. The API pauses after eight failed automatic attempts and exposes a needs-attention state. Account-wide identity deletion, real terms/purposes and a full production retention policy remain separate integration work. The demo agreement is explicitly a placeholder, not a legal policy.
+
+The browser SDK stores the app’s session in this origin’s local storage. Use HTTPS and maintain a strict content security policy when hosting. The backend delegates signature and session-revocation validation to the configured Fidj API and fails closed when it cannot verify a session.
+
+## Local scenario
+
+Only when using the loopback API, set `LOCAL_DEMO=true` to show synthetic Alex/Maya/Sam sign-in shortcuts. These accounts must be seeded by your local Fidj API; the starter does not create accounts or seed data remotely. Alex is the owner, and the owner console can grant Maya Editor access.
+
+## Entry flow
+
+The generated content app opens on `/#/signin`. Sign in, or choose **Enter anonymously** when enabled by `--anonymous true`, to open `/#/content`, containing the supplied HTML. Signed-in users can open **My privacy** separately. Sign-out and departure return to the sign-in screen. Anonymous content is public; this navigation flow is not a security boundary for static assets.
+
+Set `--anonymous false` in the generator command to remove anonymous entry and route unsigned visitors back to sign-in. This controls navigation; static HTML/assets remain public. Put confidential content behind a server-authorized endpoint.
+
+## Application modules
+
+When generated with `--module`, successful sign-in opens the copied module configured by `moduleEntry`. It runs under `/module/` on the same origin and must validate sessions/permissions independently. Its entry contains a `fidj-signin` meta URL for returning to this shared sign-in page. Module code is public static output; user data belongs behind authorized APIs. Rebuild the maintained module source and regenerate to update it; never patch its copied files here.
+
+## Connect app data rights
+
+Set `FIDJ_PRIVACY_ADAPTER_KEY` to a private random secret of at least 32 characters. Keep it exclusively in server environments; it is separate from an app JWT signing key. Register the app on the Fidj API server:
+
+```json
+{"YOUR_APP_ID":{"url":"https://your-app.example/fidj/privacy","key":"SAME_PRIVATE_RANDOM_SECRET"}}
+```
+
+Set that JSON as `FIDJ_PRIVACY_ADAPTERS` on the API. Endpoint registration is operator-managed in this milestone. HTTPS is required; explicit local mode also permits loopback HTTP. The local workspace launcher configures Studio Notes automatically. Requests contain `appId`, `subject`, `operation` and `requestId`; headers contain a millisecond timestamp and SHA-256 HMAC of `timestamp + "." + JSON.stringify(body)`. Requests older than five minutes are rejected; redirects are not followed. The handler must return the matching `requestId` and `status: "completed"` only after durable success.
+
+Keep `FIDJ_DATA_DIR` outside public assets and generated output. Use one writer process per directory. Replace `server/data-store.ts` with a transactional database implementation for multiple instances. Do not weaken the authorization check inside note writes or the atomic erase/receipt transaction. Duplicate erasures preserve later membership data. Minimal receipts contain a hashed subject and completion timestamp; receipts older than 30 days are pruned on the next write. Backups and unregistered external data remain outside this handler’s scope.
+
+
+## Check and rehearse
+
+After starting the Notes backend with its server-only adapter secret, run `npm run privacy:check`. The signed check confirms export/erase capabilities and writable storage without accessing user records. Override `FIDJ_APP_URL` for a deployed HTTPS backend. Keep this secret out of browser configuration.
+
+Run `npm run privacy:rehearse` for an isolated temporary-store HTTP scenario covering live roles, scoped export, persistence, failure and idempotent erasure. It never points at your running data directory. Groups are managed in the Fidj owner console; direct and group roles are checked live by the backend.

package/generators/app/templates/typescript/app.config.json

@@ -0,0 +1,10 @@
+{
+  "appId": "fidj-example",
+  "apiEndpoint": "https://api.sandbox.fidj.ovh/v3",
+  "dashboardUrl": "https://fidj.ovh",
+  "title": "My app",
+  "localDemo": false,
+  "allowAnonymous": true,
+  "moduleEntry": "",
+  "description": "A space to explore, with an account that puts you in control."
+}

package/generators/app/templates/typescript/gitignore

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+.env
+.env.local
+.fidj-data/

package/generators/app/templates/typescript/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "fidj-typescript-app",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc --noEmit && node scripts/build.mjs",
+    "start": "node --env-file=.env dist/server.cjs",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "build-prod": "npm run build",
+    "privacy:check": "node --env-file=.env scripts/privacy-check.mjs",
+    "privacy:rehearse": "npm run build && node --test test/server.test.mjs"
+  },
+  "dependencies": {
+    "@ofidj/node": "^3.6.24"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "esbuild": "0.28.2",
+    "typescript": "5.9.3"
+  }
+}

package/generators/app/templates/typescript/public/index.html

@@ -0,0 +1,16 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>My workspace · Fidj</title>
+    <link rel="icon" href="/fidj-logo.png" />
+    <link rel="stylesheet" href="/main.css" />
+    <script type="module" src="/main.js"></script>
+  </head>
+  <body>
+    <div id="app">
+      <main><h1>Opening your workspace…</h1></main>
+    </div>
+  </body>
+</html>