ketatlas 0.2.4 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.3.0
+
+- Standardize discoverable projects as `<name>.ketatlas/atlas.json` bundles, add `discover`, accept bundle directories in Atlas commands, and teach the bundled skill to backfill legacy projects safely.
+- Accelerate drag, wheel, keyboard and pinch camera controls while preserving pointer-anchored zoom.
+- Require agents to confirm a design system before visual mockup work, with Auto defaulting to Két Design System and explicit Carbon, Primer, Fluent 2, no-system, and custom-source options.
+
+## 0.2.5
+
+- Show separate Checks and Implemented percentage badges per workflow. Implemented includes Verified screens; project verification remains separate on the top bar. Display a dash for Checks when no checklist is recorded.
+
 ## 0.2.4
 
 - Anchor the progress detail header directly inside the modal top border and scroll only the form beneath it.

package/README.md

@@ -17,21 +17,22 @@ https://github.com/user-attachments/assets/13f24fc8-7b8e-4bda-9e02-364c120ee163
 [KetAtlas is available on npm](https://www.npmjs.com/package/ketatlas). Use Node.js 22+ and run it from any directory:
 
 ```sh
-npx --yes ketatlas@0.2.4 scaffold my-atlas --template web
-npx --yes ketatlas@0.2.4 serve my-atlas/atlas.json
-npx --yes ketatlas@0.2.4 audit my-atlas/atlas.json --strict
+npx --yes ketatlas scaffold my-atlas.ketatlas --template web
+npx --yes ketatlas discover . --json
+npx --yes ketatlas serve my-atlas.ketatlas
+npx --yes ketatlas audit my-atlas.ketatlas --strict
 ```
 
 Or install the CLI once for your user account:
 
 ```sh
-npm install --global ketatlas@0.2.4
-ketatlas scaffold my-atlas
-ketatlas serve my-atlas/atlas.json
-ketatlas audit my-atlas/atlas.json --strict
+npm install --global ketatlas
+ketatlas scaffold my-atlas.ketatlas
+ketatlas serve my-atlas.ketatlas
+ketatlas audit my-atlas.ketatlas --strict
 ```
 
-The consumer folder contains `atlas.json`, its schema, product HTML/CSS/JavaScript, local assets, and documentation. It needs no `package.json`, lockfile, `node_modules`, build step, or copy of the viewer. The CLI supplies scaffold, serving, and static audit from its own installation. `audit` leaves project files unchanged unless an output file is explicitly requested. Viewing with `serve` does not write; explicit **Save progress** writes the sibling progress file. Use `--read-only` to disable editing.
+The consumer bundle is named `<name>.ketatlas/` and contains `atlas.json`, its schema, product HTML/CSS/JavaScript, local assets, and documentation. The stable directory suffix lets desktop tools discover atlases without parsing unrelated JSON. A bundle needs no `package.json`, lockfile, `node_modules`, build step, or copy of the viewer. The CLI supplies scaffold, discovery, serving, and static audit from its own installation. `audit` leaves project files unchanged unless an output file is explicitly requested. Viewing with `serve` does not write; explicit **Save progress** writes the sibling progress file. Use `--read-only` to disable editing.
 
 Pin the version in run commands or the global installation for reproducible team workflows. Product scripts implement mock screen interactions; they are authored content, not a local installation of KetAtlas. Framework tooling and tests stay in the KetAtlas repository.
 
@@ -81,12 +82,13 @@ Open **Screens** to filter screen progress, review blockers and edit acceptance
 
 ## Commands
 
-| Command                 | Purpose                                                                                    |
-| ----------------------- | ------------------------------------------------------------------------------------------ |
-| `scaffold <directory>`  | Create a project from `basic`, `web`, or `process`. Refuses to overwrite existing content. |
-| `serve <atlas.json>`    | Start the viewer and serve local screens. Defaults to port 4178 on localhost.              |
-| `audit <atlas.json>`    | Check configuration, reachability, local files, and literal HTML/CSS references.           |
-| `validate <atlas.json>` | Validate configuration only, without reading screen files.                                 |
+| Command                    | Purpose                                                                          |
+| -------------------------- | -------------------------------------------------------------------------------- |
+| `scaffold <name.ketatlas>` | Create a bundle from `basic`, `web`, or `process`. Refuses existing content.     |
+| `discover <directory>`     | Find valid `*.ketatlas/atlas.json` bundles and report invalid bundles.           |
+| `serve <bundle\|json>`     | Start the viewer and serve local screens. Defaults to port 4178 on localhost.    |
+| `audit <bundle\|json>`     | Check configuration, reachability, local files, and literal HTML/CSS references. |
+| `validate <bundle\|json>`  | Validate configuration only, without reading screen files.                       |
 
 Use `--help` for options, `--root` when assets live above the JSON directory, and `audit --json` for CI reports. [Full CLI reference →](docs/cli.md)
 
@@ -114,7 +116,7 @@ npm ci
 npm run dev
 ```
 
-The playground includes mobile sign-in, desktop approval, and a fulfilment process. These development dependencies are not required in consumer projects. To try an unpublished checkout, use `npx --yes --package ~/dev/ketatlas ketatlas serve /path/to/my-atlas/atlas.json`.
+The playground includes mobile sign-in, desktop approval, and a fulfilment process. These development dependencies are not required in consumer projects. To try an unpublished checkout, use `npx --yes --package ~/dev/ketatlas ketatlas serve /path/to/my-atlas.ketatlas`.
 
 Stable version increases merged into `develop` are automatically published after CI verifies the package. See [Releasing](docs/releasing.md).
 

package/bin/discovery.js

@@ -0,0 +1,90 @@
+import { readFile, readdir, realpath, stat } from "node:fs/promises";
+import { basename, join, resolve } from "node:path";
+import { validateAtlas } from "../src/config.js";
+
+export const atlasDirectorySuffix = ".ketatlas";
+export const atlasManifestName = "atlas.json";
+
+const excludedDirectories = new Set([
+  ".git",
+  ".cache",
+  ".next",
+  ".venv",
+  "build",
+  "dist",
+  "node_modules",
+  "vendor",
+]);
+
+export function isAtlasDirectory(path) {
+  return basename(resolve(path)).toLowerCase().endsWith(atlasDirectorySuffix);
+}
+
+export function requireAtlasDirectory(path) {
+  const destination = resolve(path);
+  if (!isAtlasDirectory(destination))
+    throw new Error(`Atlas directories must end in ${atlasDirectorySuffix}.`);
+  return destination;
+}
+
+export async function resolveAtlasFile(target) {
+  const absolute = resolve(target);
+  const info = await stat(absolute);
+  if (!info.isDirectory()) return absolute;
+  if (!isAtlasDirectory(absolute))
+    throw new Error(`Atlas directories must end in ${atlasDirectorySuffix}.`);
+  return join(absolute, atlasManifestName);
+}
+
+async function describe(directory) {
+  const path = join(directory, atlasManifestName);
+  let config;
+  try {
+    config = JSON.parse(await readFile(path, "utf8"));
+  } catch (error) {
+    return { error: { path, message: error.message } };
+  }
+  const validation = validateAtlas(config);
+  if (!validation.valid)
+    return {
+      error: {
+        path,
+        message: validation.errors.map((issue) => `${issue.path}: ${issue.message}`).join("; "),
+      },
+    };
+  return {
+    atlas: {
+      path,
+      directory,
+      title: config.title,
+      screens: (config.screens || []).map(({ id, title, url }) => ({ id, title, url })),
+      flowCount: config.flows.length,
+    },
+  };
+}
+
+export async function discoverAtlases(root) {
+  const workspace = await realpath(resolve(root));
+  if (!(await stat(workspace)).isDirectory())
+    throw new Error("Discovery root must be a directory.");
+  const atlases = [],
+    errors = [],
+    directories = [workspace];
+  while (directories.length) {
+    const directory = directories.pop();
+    if (isAtlasDirectory(directory)) {
+      const result = await describe(directory);
+      if (result.atlas) atlases.push(result.atlas);
+      else errors.push(result.error);
+      continue;
+    }
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+      if (!entry.isDirectory() || entry.isSymbolicLink() || excludedDirectories.has(entry.name))
+        continue;
+      directories.push(join(directory, entry.name));
+    }
+  }
+  atlases.sort((a, b) => a.path.localeCompare(b.path));
+  errors.sort((a, b) => a.path.localeCompare(b.path));
+  return { version: 1, root: workspace, atlases, errors };
+}

package/bin/ketatlas.js

@@ -8,21 +8,29 @@ import { validateAtlas } from "../src/config.js";
 import { serve } from "./server.js";
 import { serveAtlas } from "./viewer.js";
 import { auditAtlas } from "./audit.js";
+import {
+  discoverAtlases,
+  isAtlasDirectory,
+  requireAtlasDirectory,
+  resolveAtlasFile,
+} from "./discovery.js";
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const help = `KetAtlas — scaffold, serve, and audit HTML workflow maps
 
-  ketatlas scaffold <directory> [--template basic|web|process]
-  ketatlas serve <atlas.json> [--port 4178] [--root directory]
-  ketatlas audit <atlas.json> [--root directory] [--json] [--strict]
-  ketatlas validate <atlas.json>
-  ketatlas progress <atlas.json> [--json] [--init]
-  ketatlas progress <atlas.json> --set <screen-id> --record <record.json> --expect <revision>
+  ketatlas scaffold <name.ketatlas> [--template basic|web|process]
+  ketatlas discover <directory> [--json]
+  ketatlas serve <name.ketatlas|atlas.json> [--port 4178] [--root directory]
+  ketatlas audit <name.ketatlas|atlas.json> [--root directory] [--json] [--strict]
+  ketatlas validate <name.ketatlas|atlas.json>
+  ketatlas progress <name.ketatlas|atlas.json> [--json] [--init]
+  ketatlas progress <name.ketatlas|atlas.json> --set <screen-id> --record <record.json> --expect <revision>
   ketatlas --version
 
 Examples:
-  npx ketatlas scaffold my-atlas
-  npx ketatlas serve my-atlas/atlas.json
-  npx ketatlas audit my-atlas/atlas.json --strict
+  npx ketatlas scaffold my-atlas.ketatlas
+  npx ketatlas discover . --json
+  npx ketatlas serve my-atlas.ketatlas
+  npx ketatlas audit my-atlas.ketatlas --strict
 
 Serve binds to 127.0.0.1. No HTML wrapper, build, account, or backend required.
 `;
@@ -61,7 +69,7 @@ async function main(args) {
       template = options.template || "basic";
     if (!["basic", "web", "process"].includes(template))
       throw new Error("Templates: basic, web, process.");
-    const destination = resolve(target);
+    const destination = requireAtlasDirectory(target);
     let existing;
     try {
       existing = await readdir(destination);
@@ -79,10 +87,25 @@ async function main(args) {
         errorOnExist: true,
       });
     console.log(
-      `Created ${destination}\n\nNext: npx ketatlas serve "${join(destination, "atlas.json")}"\nEdit atlas.json to make it yours.`,
+      `Created ${destination}\n\nNext: npx ketatlas serve "${destination}"\nEdit atlas.json to make it yours.`,
     );
     return;
   }
+  if (command === "discover") {
+    const { target, options } = parse(rest, { json: "boolean" }),
+      result = await discoverAtlases(target);
+    if (options.json) console.log(JSON.stringify(result, null, 2));
+    else {
+      for (const atlas of result.atlases)
+        console.log(`${atlas.title}\t${atlas.path}\t${atlas.screens.length} screens`);
+      for (const error of result.errors) console.error(`ERROR ${error.path}: ${error.message}`);
+      console.log(
+        `${result.atlases.length} atlas${result.atlases.length === 1 ? "" : "es"} in ${result.root}`,
+      );
+    }
+    if (result.errors.length) process.exitCode = 1;
+    return;
+  }
   if (command === "audit") {
     const { target, options } = parse(rest, {
       root: "string",
@@ -90,7 +113,7 @@ async function main(args) {
       strict: "boolean",
       output: "string",
     });
-    const report = await auditAtlas(target, options),
+    const report = await auditAtlas(await resolveAtlasFile(target), options),
       pass = report.valid && (!options.strict || report.warnings.length === 0);
     if (options.output)
       await writeFile(resolve(options.output), JSON.stringify(report, null, 2) + "\n", {
@@ -109,7 +132,7 @@ async function main(args) {
   }
   if (command === "validate") {
     const { target } = parse(rest, {}),
-      config = JSON.parse(await readFile(resolve(target), "utf8")),
+      config = JSON.parse(await readFile(await resolveAtlasFile(target), "utf8")),
       result = validateAtlas(config);
     for (const issue of result.errors) console.error(`ERROR ${issue.path}: ${issue.message}`);
     for (const issue of result.warnings) console.warn(`WARN ${issue.path}: ${issue.message}`);
@@ -130,7 +153,7 @@ async function main(args) {
       record: "string",
       expect: "string",
     });
-    const file = resolve(target),
+    const file = await resolveAtlasFile(target),
       atlas = JSON.parse(await readFile(file, "utf8"));
     const valid = validateAtlas(atlas);
     if (!valid.valid) throw new Error(valid.errors.map((e) => e.message).join("; "));
@@ -180,9 +203,14 @@ async function main(args) {
     const directory = (await stat(resolve(target))).isDirectory();
     if (directory && options.root)
       throw new Error("--root is only needed when serving an atlas JSON file.");
-    const server = directory
-      ? await serve(target, { port })
-      : await serveAtlas(target, { port, root: options.root, readOnly: options["read-only"] });
+    const server =
+      directory && !isAtlasDirectory(target)
+        ? await serve(target, { port })
+        : await serveAtlas(await resolveAtlasFile(target), {
+            port,
+            root: options.root,
+            readOnly: options["read-only"],
+          });
     console.log(
       `KetAtlas: http://127.0.0.1:${server.address().port}\nServing ${resolve(target)}\nPress Ctrl+C to stop.`,
     );

package/docs/agent-mockups.md

@@ -36,10 +36,12 @@ and preview the result. Return the serve command and verification results.
 
 `$ketatlas` is the explicit skill invocation in Codex. In other agents, use that agent's skill selector or explicitly ask it to use the installed KetAtlas skill. Keep the same product brief.
 
-The deliverable is data and product screen assets: JSON/schema, HTML/CSS/JavaScript, local assets, and documentation. Do not add a package manifest, lockfile, node_modules, or copied viewer/test tooling to make the atlas runnable. Use a global KetAtlas installation or a version-pinned npx command. Browser checks can use the agent's existing tooling outside the atlas folder.
+The deliverable is a `<name>.ketatlas/` bundle containing data and product screen assets: JSON/schema, HTML/CSS/JavaScript, local assets, and documentation. Do not add a package manifest, lockfile, node_modules, or copied viewer/test tooling to make the atlas runnable. Use a global KetAtlas installation or a version-pinned npx command. Browser checks can use the agent's existing tooling outside the atlas folder.
 
 The agent should infer routine details and record assumptions. Provide an exact list when “all screens” means a defined inventory, so missing coverage can be checked against a source.
 
+Before it creates or edits visual screens, the skill asks for one design-system choice: Auto (Két Design System), Két Design System, Carbon, GitHub Primer, Microsoft Fluent 2, no design system, or a repository URL/local path. A design system already named in the request counts as the answer. Auto uses [Két Design System](https://github.com/ketvietlab/ketjs/tree/develop/packages/design-system). The agent inspects and uses the selected system's actual tokens, components, assets, and patterns, then records the source and integration strategy in the atlas README.
+
 ## Use a saved brief for larger projects
 
 Save this template as `mockup-brief.md`, fill in the relevant fields, and ask: **“Use the KetAtlas skill to implement mockup-brief.md.”** The brief stays Markdown; do not add its planning fields to `atlas.json`.
@@ -52,7 +54,8 @@ Save this template as `mockup-brief.md`, fill in the relevant fields, and ask: *
 - Output directory:
 - Target platforms and viewport sizes:
 - Product content language:
-- Design system, existing HTML, and reference files/URLs:
+- Design system choice (Auto/Két/Carbon/Primer/Fluent 2/none/custom source):
+- Existing HTML and reference files/URLs:
 - Requested flows and screen inventory:
 - Relevant loading, empty, validation, error, and recovery states:
 - Interactions to demonstrate and synthetic demo inputs:
@@ -76,10 +79,11 @@ For an existing prototype, ask the agent to reuse its HTML and add or update the
 ## Review the result
 
 ```sh
-npx ketatlas serve ./tasks/mobile/atlas.json
-npx ketatlas audit ./tasks/mobile/atlas.json --strict
+npx ketatlas discover . --json
+npx ketatlas serve ./tasks/mobile.ketatlas
+npx ketatlas audit ./tasks/mobile.ketatlas --strict
 ```
 
 Check the delivered flow coverage against the brief. Open **Try this screen** to test the actual HTML. A successful audit confirms structural and local-file checks, not visual quality, full product coverage, or working production integrations. Intentional remote URLs require separate verification and produce strict-audit warnings.
 
-The skill lives in this repository so teams can review and evolve it alongside the schema and CLI. It works with the published `ketatlas@0.1.1` format; the skill itself can be distributed through GitHub without waiting for a new npm release.
+The skill lives in this repository so teams can review and evolve it alongside the schema and CLI. It also backfills legacy atlas directories into the discoverable bundle pattern before extending them.

package/docs/architecture.md

@@ -3,8 +3,9 @@
 KetAtlas is a static browser viewer plus a Node.js command-line toolkit. There is no database, account service or runtime npm dependency. The localhost CLI has a narrow, protected API to read and save the progress sidecar; static hosting remains read-only.
 
 ```text
-atlas.json + screen HTML
+<name>.ketatlas/atlas.json + screen HTML
         │
+        ├── discover → workspace bundle catalog
         ├── validate / audit → diagnostics and CI exit code
         │
         └── serve → built-in viewer page
@@ -17,7 +18,7 @@ atlas.json + screen HTML
 
 ## Consumer boundary
 
-KetAtlas is installed globally or executed through npx. Consumers provide JSON, a schema, HTML/CSS/JavaScript mock screens, assets, and documentation. They do not need a Node package, lockfile, development dependencies, viewer implementation, or build/test scripts to scaffold, serve, or audit a map.
+KetAtlas is installed globally or executed through npx. Consumers provide a `<name>.ketatlas/` bundle containing JSON, a schema, HTML/CSS/JavaScript mock screens, assets, and documentation. The suffix is the discovery boundary: tools inspect only its direct `atlas.json`, not arbitrary workspace JSON. Consumers do not need a Node package, lockfile, development dependencies, viewer implementation, or build/test scripts to scaffold, discover, serve, or audit a map.
 
 The package owns the CLI, viewer, validation, and framework verification. A product may have its own application tests elsewhere; those are independent of the map format. Static audit does not simulate product interactions. Agent browser checks can run through external tooling without adding a test harness to the delivered atlas folder.
 
@@ -32,7 +33,7 @@ The package owns the CLI, viewer, validation, and framework verification. A prod
 | `src/index.d.ts`  | Public TypeScript declarations.                               |
 | `styles/`         | Viewer layout and generated canonical design-system bundles.  |
 | `assets/`         | Local fonts, licenses and provenance manifest.                |
-| `bin/`            | Scaffold, JSON serving, validation and static audit.          |
+| `bin/`            | Bundle discovery, scaffold, serving, validation and audit.    |
 | `templates/`      | Self-contained starting projects included in the npm package. |
 | `examples/`       | Maintainer playground with mobile, web and process flows.     |
 | `scripts/`        | Reproducible assets, templates, schema and package checks.    |
@@ -42,7 +43,7 @@ The package owns the CLI, viewer, validation, and framework verification. A prod
 
 Flows are stacked on one canvas. A row and column grow to fit their largest node, so mobile and desktop aspect ratios can coexist. The layout respects authored grid positions. Arrows use orthogonal routes and a small lane offset; this is not an obstacle-avoiding graph-layout engine. Use nearby grid cells and concise labels for readable large diagrams.
 
-Camera changes use an animation frame and a CSS transform. Only the nearest visible screen cards receive iframes, up to the configured cap. Below the preview threshold, all cards show placeholders. This limits embedded-page cost; every node and edge still has a DOM element. There is no claim of unlimited graph size.
+Camera changes use an animation frame and a CSS transform. Drag, wheel, keyboard and pinch input use shared accelerated motion constants while zoom remains anchored under the pointer. Only the nearest visible screen cards receive iframes, up to the configured cap. Below the preview threshold, all cards show placeholders. This limits embedded-page cost; every node and edge still has a DOM element. There is no claim of unlimited graph size.
 
 The inspector reuses the same screen URL at its declared viewport dimensions, with no extra side padding. Its iframe is removed when closed. Reopening a screen loads a fresh instance; editing a prototype is not persistent business state.
 

package/docs/authoring.md

@@ -5,8 +5,8 @@ Start with a user goal: sign in, approve a purchase, or deliver an order. Give e
 ## 1. Create a starting point
 
 ```sh
-ketatlas scaffold ./customer-journeys --template basic
-ketatlas serve ./customer-journeys/atlas.json
+ketatlas scaffold ./customer-journeys.ketatlas --template basic
+ketatlas serve ./customer-journeys.ketatlas
 ```
 
 Open a card with a double-click. The preview is actual HTML; links and JavaScript inside it can work independently of the map. Edit those files before adding more nodes.
@@ -41,7 +41,7 @@ Click a node to highlight incoming/outgoing arrows and follow a next-step button
 ## 5. Audit before sharing
 
 ```sh
-ketatlas audit ./customer-journeys/atlas.json --strict
+ketatlas audit ./customer-journeys.ketatlas --strict
 ```
 
 Keep the JSON and screens in your project's repository. Review changes in pull requests. Share the directory or run the same serve command in the recipient's checkout. No hosted account or service state is required.

package/docs/cli.md

@@ -1,30 +1,41 @@
 # CLI reference
 
-Install once with `npm install --global ketatlas@0.1.1`, or prefix commands with `npx --yes ketatlas@0.1.1`. No dependency installation is required in the consumer directory. `node /path/to/ketatlas/bin/ketatlas.js` is also available to framework maintainers.
+Install once with `npm install --global ketatlas`, or prefix commands with `npx --yes ketatlas`. No dependency installation is required in the consumer directory. `node /path/to/ketatlas/bin/ketatlas.js` is also available to framework maintainers.
 
 A consumer keeps only its JSON/schema, product HTML/CSS/JavaScript, assets, and documentation. The package manifest, lockfile, development scripts, and browser test dependencies belong to the tool. Normal `serve`, `validate`, and `audit` calls do not create files in the consumer; `audit --output` is an explicit exception.
 
 ## Scaffold
 
 ```sh
-ketatlas scaffold ./journeys
-ketatlas scaffold ./approvals --template web
-ketatlas scaffold ./operations --template process
+ketatlas scaffold ./journeys.ketatlas
+ketatlas scaffold ./approvals.ketatlas --template web
+ketatlas scaffold ./operations.ketatlas --template process
 ```
 
 `basic` is the default: two interactive mobile pages and one flow. `web` contains desktop purchase approval pages. `process` contains notes and an external handoff, without HTML screens. Every template includes a local JSON Schema for editor completion and a README. Product HTML and its styles belong to the new project.
 
-`init` is an alias for `scaffold`. The destination must be missing or empty. Existing files are never overwritten; there is no `--force` flag.
+`init` is an alias for `scaffold`. The destination must end in `.ketatlas` and be missing or empty. Existing files are never overwritten; there is no `--force` flag.
+
+## Discover bundles
+
+```sh
+ketatlas discover .
+ketatlas discover . --json
+```
+
+Discovery walks the selected workspace for exact `*.ketatlas/atlas.json` bundles. It skips dependency, generated, cache, Git and vendor directories; it does not parse unrelated JSON. The JSON report contains `version`, `root`, `atlases`, and `errors`, including each atlas title, path, directory, screens and flow count. Invalid bundle manifests are reported and produce exit code 1.
+
+Legacy manifest paths remain valid command arguments, but discovery intentionally ignores them. Migrate a self-contained legacy directory by renaming it to `<name>.ketatlas`; see the bundled skill for mixed-directory migration safeguards.
 
 ## Serve a JSON file
 
 ```sh
-ketatlas serve ./tasks/onboarding/atlas.json
-ketatlas serve ./tasks/onboarding/atlas.json --port 4180
-ketatlas serve ./tasks/onboarding/atlas.json --root .
+ketatlas serve ./tasks/onboarding.ketatlas
+ketatlas serve ./tasks/onboarding.ketatlas --port 4180
+ketatlas serve ./legacy/atlas.json --root .
 ```
 
-The tool supplies the viewer page. It validates the JSON at startup, serves your files, and mounts the atlas at `/`. The default file root is the JSON file's directory. Choose `--root` when a relative URL points to a sibling directory outside that default root. The JSON must be inside the selected root.
+The tool supplies the viewer page. It validates the JSON at startup, serves your files, and mounts the atlas at `/`. Passing a `.ketatlas` directory resolves its `atlas.json` and uses the bundle as the file root. Explicit legacy JSON paths still support `--root` when a relative URL points outside the manifest directory.
 
 Open the printed localhost URL. Changes appear after refreshing; there is no hot reload or authoring server state. Use `?flow=your-flow-id` or `?screen=your-screen-id` to open a specific part of the map. An unknown ID falls back to the first flow.
 
@@ -35,10 +46,10 @@ The `/__ketatlas__/` route is reserved for viewer assets. Dotfiles and paths res
 ## Audit
 
 ```sh
-ketatlas audit ./atlas.json
-ketatlas audit ./atlas.json --root .. --strict
-ketatlas audit ./atlas.json --json
-ketatlas audit ./atlas.json --json --output audit-report.json
+ketatlas audit ./tasks/onboarding.ketatlas
+ketatlas audit ./tasks/onboarding.ketatlas --strict
+ketatlas audit ./tasks/onboarding.ketatlas --json
+ketatlas audit ./tasks/onboarding.ketatlas --json --output audit-report.json
 ```
 
 Audit checks:
@@ -64,7 +75,7 @@ Exit codes:
 ## Validate and version
 
 ```sh
-ketatlas validate ./atlas.json
+ketatlas validate ./tasks/onboarding.ketatlas
 ketatlas --version
 ketatlas --help
 ```
@@ -73,4 +84,4 @@ ketatlas --help
 
 ## Screen progress
 
-`progress <atlas.json> --json` reads the progress record, content revision and unique-screen summary. `--init` creates a missing sidecar. `--set <screen-id> --record <record.json> --expect <revision>` replaces one record with conflict detection. `serve <atlas.json> --read-only` disables local progress writes. See [Screen progress](progress.md) for examples and persistence rules.
+`progress <bundle|atlas.json> --json` reads the progress record, content revision and unique-screen summary. `--init` creates a missing sidecar. `--set <screen-id> --record <record.json> --expect <revision>` replaces one record with conflict detection. `serve <bundle|atlas.json> --read-only` disables local progress writes. See [Screen progress](progress.md) for examples and persistence rules.

package/docs/migration.md

@@ -1,5 +1,11 @@
 # Migrating the KétSuite mobile map
 
+## Bundle layout backfill
+
+Current projects use `<name>.ketatlas/atlas.json`. For a legacy self-contained Atlas directory, rename the whole directory so relative screen, style and asset URLs remain unchanged. When `atlas.json` shares a directory with unrelated application code, create a sibling `<name>.ketatlas` bundle, move only Atlas-owned files, and update relative URLs for resources that intentionally remain outside it. Keep one canonical manifest, then run `ketatlas discover <workspace> --json`, `ketatlas validate <name>.ketatlas`, and `ketatlas audit <name>.ketatlas --strict`.
+
+The CLI continues to accept a direct legacy JSON path so migration can be audited before and after the move. Discovery intentionally reports only the standard bundle pattern.
+
 The original mobile map remains in its project. KetAtlas does not copy its business data or change the mobile repository. The extraction generalizes the viewer; project migration is a separate configuration change.
 
 ## Field mapping

package/docs/progress.md

@@ -6,9 +6,9 @@ Screen and state preview footers show the shared screen status, blockers and lin
 
 ## Sidebar and project completion
 
-Project-wide verified/checklist percentages and blocker counts appear in the top bar beside **Screens**. The sidebar shows one compact numeric badge after each workflow’s step count (`2 steps [30%]`). **Verified %** is the number of Verified screens divided by the total unique screens in that scope. Repeated nodes and error variants count once; note/external nodes do not count. Screenless flows have no badge. Percentages round down so unfinished work cannot appear as 100%.
+Project-wide verified/checklist percentages and blocker counts appear in the top bar beside **Screens**. The sidebar shows two badges after each workflow’s step count: **Checks %** (completed recorded acceptance checks / all recorded checks for unique screens) and **Implemented %** (screens with Implemented or Verified status / all unique screens). The compact labels are `30% checks` and `20% impl.`; tooltips spell out the definitions. In progress and In review screens do not count as implemented. Repeated nodes and error variants count once; note/external nodes do not count. Screenless flows have no badge. Flows with no recorded checks show **—**, not a measured 0%. Percentages round down so unfinished checks cannot appear as 100%.
 
-The badge tooltip and accessible label include status counts, blockers and **Checks %**, which counts completed recorded acceptance checks over all recorded checks, with an explicit unscoped-screen count when checklists are missing. This is not an estimate of effort, and 100% of a partial checklist does not make a screen Verified. Saving or refreshing progress updates the sidebar; changing or searching workflows preserves the current progress.
+The badge tooltip and accessible label include completed/total checks, status counts, blockers, verified-screen completion, and unscoped-screen counts when checklists are missing. Checklist completion is not an estimate of effort or verified screen completion: 100% of a partial checklist does not make a screen Verified. Verified % on the top bar remains the number of Verified screens divided by all unique project screens. Saving or refreshing progress updates the sidebar; changing or searching workflows preserves the current progress.
 
 ## Status and scope
 
@@ -71,11 +71,11 @@ Evidence kinds are `pr`, `test`, `release`, `reference`. Required fields: `id`,
 ## Editing locally and from agents
 
 ```sh
-npx --yes ketatlas@0.2.4 serve atlas.json
-npx --yes ketatlas@0.2.4 serve atlas.json --read-only
-npx --yes ketatlas@0.2.4 progress atlas.json --init
-npx --yes ketatlas@0.2.4 progress atlas.json --json
-npx --yes ketatlas@0.2.4 progress atlas.json --set sign-in --record record.json --expect REVISION_FROM_READ
+npx --yes ketatlas serve ./account-access.ketatlas
+npx --yes ketatlas serve ./account-access.ketatlas --read-only
+npx --yes ketatlas progress ./account-access.ketatlas --init
+npx --yes ketatlas progress ./account-access.ketatlas --json
+npx --yes ketatlas progress ./account-access.ketatlas --set sign-in --record record.json --expect REVISION_FROM_READ
 ```
 
 `--init` explicitly creates Unassessed records and refuses an existing progress file. `--set` replaces one complete screen record; preserve existing checklist IDs, evidence and state references. Read the revision with `--json` first. Do not retry a stale revision by blindly substituting a new one: reload and reconcile changes. `updatedAt` is stamped on successful record writes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ketatlas",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "description": "Interactive HTML maps for screens, workflows, and user journeys.",
   "type": "module",
   "license": "MIT",

package/skills/ketatlas/SKILL.md

@@ -5,7 +5,7 @@ description: Create or update interactive HTML mockups and workflow maps in KetA
 
 # KetAtlas
 
-Deliver an editable project containing actual HTML screens and a version 1 `atlas.json` that `npx ketatlas serve` can open. KetAtlas supplies the draggable viewer; the agent authors the product mockups and their flow graph. A screenshot gallery or a Mermaid diagram alone is not this deliverable.
+Deliver an editable `<name>.ketatlas/` bundle containing actual HTML screens and a version 1 `atlas.json` that `npx ketatlas serve` can open. KetAtlas supplies the draggable viewer; the agent authors the product mockups and their flow graph. A screenshot gallery or a Mermaid diagram alone is not this deliverable.
 
 ## Read the brief and choose the scope
 
@@ -18,24 +18,56 @@ Use the user's requirements, existing project files, and design references to de
 
 A brief may be a chat message or a Markdown file; it is not another KetAtlas JSON format. If details are missing, use reasonable defaults and record assumptions. Ask only for information that materially blocks the requested result. Do not introduce unrelated flows or build a production backend to make a mockup work.
 
-Use the supplied product design system when one exists. The starter uses KetJS styles, but KetAtlas can embed product HTML using any design system. For one shared iOS/Android prototype, create one HTML implementation with reusable styles and states unless separate variants were requested.
+## Choose the design system
+
+Before scaffolding or editing visual screens, ask the user to choose a design system unless the current request already makes the choice explicit. Present these options in one concise prompt:
+
+1. **Auto (recommended)** — use [Két Design System](https://github.com/ketvietlab/ketjs/tree/develop/packages/design-system).
+2. **Két Design System** — use the same canonical Két source explicitly.
+3. **Carbon Design System**.
+4. **GitHub Primer**.
+5. **Microsoft Fluent 2**.
+6. **No design system** — create product-specific shared CSS without claiming conformance to a named system.
+7. **Custom source** — ask for a repository URL or local design-system path if it was not included with the selection.
+
+Do not start visual screen implementation until the user answers. If the user explicitly delegates the choice to the agent, treat that as **Auto**. This selection prompt is still required for an existing atlas; its documented/current system may be offered as the likely choice. A request that already names a system or supplies a design-system source counts as an answer and must not be asked again.
+
+Inspect the selected source, its usage documentation, tokens, components, icons, and relevant product patterns before mocking. Reuse its actual public assets and composition patterns when available; do not merely imitate its color palette. Replace incompatible starter styling rather than layering multiple design systems. For one shared iOS/Android prototype, create one HTML implementation with reusable styles and states unless separate variants were requested.
+
+Prefer a local adapter descriptor with `schemaVersion: "ketatlas.design-system-adapter.v1"` when the selected design system provides one. Discover it from the user-supplied path, a repository `design-system.atlas.json`, or the package's documented `./atlas/profile.json` export. Read the descriptor before using its assets or commands; do not assume capabilities it does not declare. If there is no adapter, use the design system through its documented HTML/CSS interface and record that no reproducible adapter lock is available.
+
+For Két Design System, prefer the descriptor exported at `@ketvietlab/design-system/atlas/profile.json` and its declared `ket-design-system-atlas` materializer. Read that descriptor for asset names, root attributes, slots, hooks, and state ownership instead of hard-coding them.
+
+Keep the atlas self-contained and dependency-free. Do not add a consumer package installation or custom bundler just to use a design system. Materialize or copy permitted static assets only when the selected source supports it, preserve required notices, and do not rely on remote runtime assets when the requested mockup must work offline. Record the selected system, source URL/path, pinned version or commit when known, adapter/asset strategy, and any license or fidelity limitation in the bundle README.
 
 ## Scaffold or extend
 
 Node.js 22 or newer is required. For a new, empty destination:
 
 ```sh
-npx --yes ketatlas scaffold ./tasks/mockups --template basic
+npx --yes ketatlas scaffold ./tasks/mockups.ketatlas --template basic
 ```
 
 Choose `basic` for mobile, `web` for desktop, or `process` for steps without UI. These are starting examples, not required product flows. Replace their sample content with the requested product.
 
-For an existing atlas, read and edit its JSON and screen files directly. Preserve useful IDs and URLs; scaffold refuses a nonempty directory and has no `--force` option. Pin the CLI version in the README commands (for example `npx --yes ketatlas@0.1.1 serve atlas.json`) or use a global installation. A consumer atlas does not need a local package installation.
+For an existing atlas, read and edit its JSON and screen files directly. Preserve useful IDs and URLs; scaffold refuses a nonempty directory and has no `--force` option. Pin the CLI version in the README commands or use a global installation. A consumer atlas does not need a local package installation.
+
+### Backfill legacy projects
+
+Before changing an existing atlas, run `ketatlas discover <workspace> --json`. If its manifest is not located at `<name>.ketatlas/atlas.json`, migrate it as part of the task:
+
+1. Inventory the manifest, sibling progress file, schema, README, screens, styles and assets. Record every relative `$schema`, screen URL and node URL before moving anything.
+2. If the containing directory is a self-contained Atlas project, rename that directory to a concise `<name>.ketatlas`; moving the whole directory preserves relative URLs.
+3. If the manifest shares a directory with unrelated application code, create a sibling `<name>.ketatlas` bundle. Move only Atlas-owned files, preserve Git history when possible, and rewrite relative paths for resources that intentionally remain outside the bundle.
+4. Keep one canonical manifest. Do not leave a copied legacy `atlas.json` behind or delete files whose ownership is unclear.
+5. Run `ketatlas discover <workspace> --json`, `ketatlas validate <name>.ketatlas`, and `ketatlas audit <name>.ketatlas --strict` after migration. Fix discovery errors and broken paths before editing product flows.
+
+Legacy JSON paths remain accepted by the CLI for migration, but new and updated deliverables must use the bundle pattern so desktop tools can discover them without scanning arbitrary JSON.
 
 A self-contained project typically has:
 
 ```text
-tasks/mockups/
+tasks/mockups.ketatlas/
   atlas.json
   ketatlas.schema.json
   screens/                 HTML pages and shared CSS/JavaScript
@@ -45,7 +77,7 @@ tasks/mockups/
 
 Keep product assets inside the served directory when practical. Deliver JSON/schema, screen HTML/CSS/JavaScript, assets, and documentation. Do not scaffold a `package.json`, lockfile, `node_modules`, asset build scripts, or a copied viewer/test harness in the atlas folder just to use KetAtlas. The installed CLI supplies scaffold, serve, validate, and audit. Browser verification can use the agent's external tooling. Preserve unrelated application tooling when extending an existing repository.
 
-Do not create a wrapper viewer or a custom canvas: `serve atlas.json` provides it.
+Do not create a wrapper viewer or a custom canvas: `serve ./tasks/mockups.ketatlas` provides it.
 
 ## Model the journey
 
@@ -123,9 +155,10 @@ The default iframe sandbox allows scripts and forms but gives the page an opaque
 Run from the user's project with the same root for audit and serve:
 
 ```sh
-npx --yes ketatlas validate ./tasks/mockups/atlas.json
-npx --yes ketatlas audit ./tasks/mockups/atlas.json --strict
-npx --yes ketatlas serve ./tasks/mockups/atlas.json
+npx --yes ketatlas discover . --json
+npx --yes ketatlas validate ./tasks/mockups.ketatlas
+npx --yes ketatlas audit ./tasks/mockups.ketatlas --strict
+npx --yes ketatlas serve ./tasks/mockups.ketatlas
 ```
 
 Use `--root .` on both audit and serve if screens or assets intentionally live outside the atlas directory but inside the project. Use `--port 4180` or another free port when necessary. Refresh after file edits; there is no hot reload.
@@ -138,8 +171,8 @@ Update the project's README with flow-to-screen/state coverage, assumptions, dem
 
 ## Maintain screen delivery progress
 
-When implementing or reviewing screens, track progress in the sibling `<atlas-name>.progress.json`. Use KetAtlas 0.2.0 or newer. Keep version 1 workflow JSON unchanged. Read `ketatlas progress atlas.json --json`, preserve existing evidence/check IDs and state references, then update one record with `--set <screen-id> --record <record.json> --expect <revision>`. Re-read and reconcile conflicts instead of overwriting another writer. Run `audit` after updates.
+When implementing or reviewing screens, track progress in `atlas.progress.json` beside the bundle manifest. Keep version 1 workflow JSON unchanged. Read `ketatlas progress <name>.ketatlas --json`, preserve existing evidence/check IDs and state references, then update one record with `--set <screen-id> --record <record.json> --expect <revision>`. Re-read and reconcile conflicts instead of overwriting another writer. Run `audit` after updates.
 
 Map task scope to screen IDs before assigning progress. Start unknown coverage at `unassessed`; a mockup is not implementation evidence. Use `planned`, `in_progress`, `in_review`, `implemented`, `verified` with a separate blocker reason/next action. Link PRs and exact merge commits, pin/release evidence, and test evidence at the revision/environment actually checked. Do not infer deployment, full screen coverage or verification from a PR merge or green aggregate CI. Completed acceptance checks need evidence; `verified` requires passed test evidence with revision and environment for every recorded check and no blocker. Track error/recovery states using check `nodes` references. Leave unrelated or unreviewed product surfaces unassessed and say why. See `docs/progress.md` in the package for the complete contract.
 
-Sidebar percentages distinguish Verified screens from completed recorded checks. Do not assign arbitrary weights to intermediate statuses or remove unknown/unscoped screens to inflate completion. Workflow counts deduplicate screen IDs, including variants; process-only flows have no screen percentage.
+Sidebar badges show Checks (completed recorded checks / all recorded checks) and Implemented (Implemented + Verified screens / all unique screens). No recorded checks shows — for Checks. Verified-screen completion stays separate on the project top bar. Do not assign arbitrary weights to intermediate statuses or remove unknown/unscoped screens to inflate completion. Workflow counts deduplicate screen IDs, including variants; process-only flows have no screen percentage.

package/src/index.js

@@ -12,6 +12,16 @@ import { template, escapeHTML as e } from "./template.js";
 import { icons } from "./icons.js";
 export { validateAtlas, AtlasValidationError } from "./config.js";
 
+const cameraMotion = Object.freeze({
+  dragPan: 1.35,
+  wheelPan: 1.45,
+  wheelZoom: 0.0032,
+  pinchZoom: 1.2,
+  zoomStep: 1.3,
+  keyPan: 120,
+  keyPanLarge: 260,
+});
+
 /** Mount an isolated viewer. Await atlas.ready before measuring or focusing it. */
 export function createAtlas(container, input, options = {}) {
   if (!(container instanceof HTMLElement))
@@ -136,7 +146,7 @@ export function createAtlas(container, input, options = {}) {
               ).includes(q),
           );
           return matches.length
-            ? `<section><h2 class="flow-group-title">${e(group)}</h2>${matches.map((f) => `<button class="flow-link ${f === current ? "active" : ""}" data-flow="${f.id}" ${f === current ? 'aria-current="true"' : ""}><span class="flow-number">${String(f.index + 1).padStart(2, "0")}</span><span class="flow-link-copy"><strong>${e(f.title)}</strong><small>${f.nodes.length} steps <span class="flow-progress" data-progress-flow="${f.id}"></span></small></span></button>`).join("")}</section>`
+            ? `<section><h2 class="flow-group-title">${e(group)}</h2>${matches.map((f) => `<button class="flow-link ${f === current ? "active" : ""}" data-flow="${f.id}" ${f === current ? 'aria-current="true"' : ""}><span class="flow-number">${String(f.index + 1).padStart(2, "0")}</span><span class="flow-link-copy"><strong>${e(f.title)}</strong><small>${f.nodes.length} steps <span class="flow-progress-group" data-progress-flow="${f.id}"></span></small></span></button>`).join("")}</section>`
             : "";
         })
         .join("") || '<p class="mock-filter-empty">No matching workflows.</p>';
@@ -429,10 +439,8 @@ export function createAtlas(container, input, options = {}) {
     pointers.set(event.pointerId, point(event));
     if (pointers.size >= 2 && pinch) {
       const [a, b] = [...pointers.values()],
-        z = Math.max(
-          0.18,
-          Math.min(2.2, (pinch.z * Math.hypot(a.x - b.x, a.y - b.y)) / Math.max(1, pinch.distance)),
-        );
+        ratio = Math.hypot(a.x - b.x, a.y - b.y) / Math.max(1, pinch.distance),
+        z = Math.max(0.18, Math.min(2.2, pinch.z * Math.pow(ratio, cameraMotion.pinchZoom)));
       view = { z, x: (a.x + b.x) / 2 - pinch.worldX * z, y: (a.y + b.y) / 2 - pinch.worldY * z };
       suppressClick = true;
       schedule();
@@ -445,8 +453,8 @@ export function createAtlas(container, input, options = {}) {
     if (Math.hypot(dx, dy) > 4) drag.moved = true;
     if (drag.moved) {
       viewport.classList.add("dragging");
-      view.x = drag.x + dx;
-      view.y = drag.y + dy;
+      view.x = drag.x + dx * cameraMotion.dragPan;
+      view.y = drag.y + dy * cameraMotion.dragPan;
       schedule();
     }
   });
@@ -477,10 +485,16 @@ export function createAtlas(container, input, options = {}) {
       event.preventDefault();
       if (event.ctrlKey || event.metaKey) {
         const p = point(event);
-        zoomTo(view.z * Math.exp(-event.deltaY * 0.002), p.x, p.y);
+        zoomTo(view.z * Math.exp(-event.deltaY * cameraMotion.wheelZoom), p.x, p.y);
       } else {
-        view.x -= event.deltaX;
-        view.y -= event.deltaY;
+        const unit =
+          event.deltaMode === WheelEvent.DOM_DELTA_LINE
+            ? 16
+            : event.deltaMode === WheelEvent.DOM_DELTA_PAGE
+              ? viewport.clientHeight
+              : 1;
+        view.x -= event.deltaX * unit * cameraMotion.wheelPan;
+        view.y -= event.deltaY * unit * cameraMotion.wheelPan;
         syncCurrentFromPan();
         schedule();
       }
@@ -489,17 +503,17 @@ export function createAtlas(container, input, options = {}) {
   );
   viewport.addEventListener("keydown", (event) => {
     if (event.target.closest("button,a,input") || $("screen-dialog").open) return;
-    const step = event.shiftKey ? 180 : 80;
+    const step = event.shiftKey ? cameraMotion.keyPanLarge : cameraMotion.keyPan;
     if (event.key === "ArrowLeft") view.x += step;
     else if (event.key === "ArrowRight") view.x -= step;
     else if (event.key === "ArrowUp") view.y += step;
     else if (event.key === "ArrowDown") view.y -= step;
     else if (["+", "="].includes(event.key)) {
-      zoomTo(view.z * 1.2);
+      zoomTo(view.z * cameraMotion.zoomStep);
       event.preventDefault();
       return;
     } else if (event.key === "-") {
-      zoomTo(view.z / 1.2);
+      zoomTo(view.z / cameraMotion.zoomStep);
       event.preventDefault();
       return;
     } else if (event.key.toLowerCase() === "f") {
@@ -566,8 +580,8 @@ export function createAtlas(container, input, options = {}) {
     if (button) progressUI.edit(button.dataset.editProgress);
   });
   $("flow-search").addEventListener("input", sidebar);
-  $("zoom-in").onclick = () => zoomTo(view.z * 1.2);
-  $("zoom-out").onclick = () => zoomTo(view.z / 1.2);
+  $("zoom-in").onclick = () => zoomTo(view.z * cameraMotion.zoomStep);
+  $("zoom-out").onclick = () => zoomTo(view.z / cameraMotion.zoomStep);
   $("zoom-reset").onclick = () => zoomTo(1);
   $("zoom-fit").onclick = fitFlow;
   $("minimap-fit").onclick = fitFlow;

package/src/progress-ui.js

@@ -58,15 +58,35 @@ export function mountProgress(root, config, initial, options, selectScreen) {
         .map(([key, label]) => `${summary.counts[key]} ${label.toLowerCase()}`)
         .join(" · ");
       const checks = summary.checks;
-      const details = `${summary.verifiedPercent}% verified · ${summary.counts.verified}/${summary.total} screens. ${statuses}${summary.blocked ? ` · ${summary.blocked} blocked` : ""}. ${checks.total ? `Checks ${checks.percent}% · ${checks.done}/${checks.total}` : "No checks recorded"}${checks.unscoped ? ` · ${checks.unscoped} unscoped` : ""}.`;
+      const implemented = summary.counts.implemented + summary.counts.verified;
+      const implementedPercent = Math.floor((implemented / summary.total) * 100);
+      const details = `${checks.total ? `Checks ${checks.percent}% · ${checks.done}/${checks.total}. ` : "No checks recorded. "}${summary.verifiedPercent}% verified · ${summary.counts.verified}/${summary.total} screens. ${statuses}${summary.blocked ? ` · ${summary.blocked} blocked` : ""}${checks.unscoped ? ` · ${checks.unscoped} unscoped` : ""}.`;
       if (project) {
         el.innerHTML = `<span><b>${summary.verifiedPercent}%</b> verified</span><span><b>${checks.percent ?? "—"}${checks.percent === null ? "" : "%"}</b> checks</span>${summary.blocked ? `<span class="project-blocked"><b>${summary.blocked}</b> blocked</span>` : ""}`;
-      } else el.textContent = `${summary.verifiedPercent}%`;
+      } else {
+        const metric = (name, label, percent, description) =>
+          `<span class="flow-progress" data-metric="${name}" data-tone="${summary.blocked ? "blocked" : percent === 100 ? "complete" : "pending"}" title="${e(description)}" aria-label="${e(description)}">${percent === null ? "—" : `${percent}%`} ${label}</span>`;
+        el.innerHTML =
+          metric(
+            "checks",
+            "checks",
+            checks.percent,
+            checks.total
+              ? `Checks ${checks.percent}%: ${checks.done}/${checks.total} recorded checks completed`
+              : "Checks: no recorded checklist",
+          ) +
+          metric(
+            "implemented",
+            "impl.",
+            implementedPercent,
+            `Implemented ${implementedPercent}%: ${implemented}/${summary.total} screens have Implemented or Verified status`,
+          );
+      }
       el.title = details;
       el.setAttribute("aria-label", details);
       el.dataset.tone = summary.blocked
         ? "blocked"
-        : summary.verifiedPercent === 100
+        : (project ? summary.verifiedPercent : checks.percent) === 100
           ? "complete"
           : "pending";
     }

package/styles/ketatlas.css

@@ -1440,3 +1440,13 @@ a svg {
     --progress-dialog-padding: var(--kv-space-3);
   }
 }
+
+.flow-progress-group {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--kv-space-1);
+  vertical-align: middle;
+}
+.flow-progress-group[hidden] {
+  display: none;
+}

package/templates/basic/README.md

@@ -1,14 +1,14 @@
 # My KetAtlas project
 
-Run with Node.js 22 or newer:
+This directory must keep its `.ketatlas` suffix. Run with Node.js 22 or newer:
 
 ```sh
-npx ketatlas serve atlas.json
-npx ketatlas audit atlas.json --strict
+npx ketatlas serve .
+npx ketatlas audit . --strict
 ```
 
-Edit `atlas.json` to change nodes, edges, and screen URLs. Screen URLs are relative to that file. Refresh the browser after editing. No wrapper HTML, package manifest, lockfile, node_modules, or build step is needed. Alternatively, install the CLI once with npm install --global ketatlas@0.2.4 and use ketatlas serve atlas.json.
+Edit `atlas.json` to change nodes, edges, and screen URLs. Screen URLs are relative to that file. Refresh the browser after editing. No wrapper HTML, package manifest, lockfile, node_modules, or build step is needed. Alternatively, install the CLI once with npm install --global ketatlas and use ketatlas serve .
 
 Edit the HTML files in screens/ to replace the sample product. styles/design-system.css is generated from the pinned KetJS design system; do not manually fork its tokens.
 
-Open **Screens** in the viewer to review or edit delivery progress. Saving writes atlas.progress.json beside the workflow; use --read-only to disable editing. You can initialize records with ketatlas progress atlas.json --init. Keep this directory in your own project repository. The schema provides editor completion. See https://github.com/ketvietlab/ketatlas for the full API, CLI, and configuration reference.
+Open **Screens** in the viewer to review or edit delivery progress. Saving writes atlas.progress.json beside the workflow; use --read-only to disable editing. You can initialize records with ketatlas progress . --init. Keep this directory in your own project repository. The schema provides editor completion. See https://github.com/ketvietlab/ketatlas for the full API, CLI, and configuration reference.

package/templates/process/README.md

@@ -1,14 +1,14 @@
 # My KetAtlas project
 
-Run with Node.js 22 or newer:
+This directory must keep its `.ketatlas` suffix. Run with Node.js 22 or newer:
 
 ```sh
-npx ketatlas serve atlas.json
-npx ketatlas audit atlas.json --strict
+npx ketatlas serve .
+npx ketatlas audit . --strict
 ```
 
-Edit `atlas.json` to change nodes, edges, and screen URLs. Screen URLs are relative to that file. Refresh the browser after editing. No wrapper HTML, package manifest, lockfile, node_modules, or build step is needed. Alternatively, install the CLI once with npm install --global ketatlas@0.2.4 and use ketatlas serve atlas.json.
+Edit `atlas.json` to change nodes, edges, and screen URLs. Screen URLs are relative to that file. Refresh the browser after editing. No wrapper HTML, package manifest, lockfile, node_modules, or build step is needed. Alternatively, install the CLI once with npm install --global ketatlas and use ketatlas serve .
 
 This template models a process without HTML screens. Add a screen registry and screen nodes when needed.
 
-Open **Screens** in the viewer to review or edit delivery progress. Saving writes atlas.progress.json beside the workflow; use --read-only to disable editing. You can initialize records with ketatlas progress atlas.json --init. Keep this directory in your own project repository. The schema provides editor completion. See https://github.com/ketvietlab/ketatlas for the full API, CLI, and configuration reference.
+Open **Screens** in the viewer to review or edit delivery progress. Saving writes atlas.progress.json beside the workflow; use --read-only to disable editing. You can initialize records with ketatlas progress . --init. Keep this directory in your own project repository. The schema provides editor completion. See https://github.com/ketvietlab/ketatlas for the full API, CLI, and configuration reference.

package/templates/web/README.md

@@ -1,14 +1,14 @@
 # My KetAtlas project
 
-Run with Node.js 22 or newer:
+This directory must keep its `.ketatlas` suffix. Run with Node.js 22 or newer:
 
 ```sh
-npx ketatlas serve atlas.json
-npx ketatlas audit atlas.json --strict
+npx ketatlas serve .
+npx ketatlas audit . --strict
 ```
 
-Edit `atlas.json` to change nodes, edges, and screen URLs. Screen URLs are relative to that file. Refresh the browser after editing. No wrapper HTML, package manifest, lockfile, node_modules, or build step is needed. Alternatively, install the CLI once with npm install --global ketatlas@0.2.4 and use ketatlas serve atlas.json.
+Edit `atlas.json` to change nodes, edges, and screen URLs. Screen URLs are relative to that file. Refresh the browser after editing. No wrapper HTML, package manifest, lockfile, node_modules, or build step is needed. Alternatively, install the CLI once with npm install --global ketatlas and use ketatlas serve .
 
 Edit the HTML files in screens/ to replace the sample product. styles/design-system.css is generated from the pinned KetJS design system; do not manually fork its tokens.
 
-Open **Screens** in the viewer to review or edit delivery progress. Saving writes atlas.progress.json beside the workflow; use --read-only to disable editing. You can initialize records with ketatlas progress atlas.json --init. Keep this directory in your own project repository. The schema provides editor completion. See https://github.com/ketvietlab/ketatlas for the full API, CLI, and configuration reference.
+Open **Screens** in the viewer to review or edit delivery progress. Saving writes atlas.progress.json beside the workflow; use --read-only to disable editing. You can initialize records with ketatlas progress . --init. Keep this directory in your own project repository. The schema provides editor completion. See https://github.com/ketvietlab/ketatlas for the full API, CLI, and configuration reference.