ketatlas 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,6 +1,22 @@
 # Changelog
 
-## 0.1.0 — Initial scaffold
+## 0.2.0
+
+- Track delivery per screen in a separate progress JSON, with acceptance checks, blockers, ownership, task references and PR/test/release evidence.
+- Review all screens with filters and shared map badges; edit progress using the local viewer or revision-checked CLI.
+- Refuse stale writes and unsupported verification claims; keep static hosting read-only and existing version 1 workflows compatible.
+- Audit progress references, provide a public schema/API, and test browser editing, concurrency and packaged installation.
+
+## 0.1.1 — 2026-09-04
+
+- Publish the tested archive through an absolute file path; support guarded retries after a CI workflow fix.
+
+- Clarify the consumer contract: JSON, product screens, assets, and docs only; verify global and npx usage without project manifests or dependencies.
+
+- Portable KetAtlas agent skill and a product-brief workflow for generating compatible interactive HTML mockups.
+- Automatically publish verified stable version increases from `develop`, with duplicate-release protection and npm provenance.
+
+## 0.1.0 — 2026-09-04
 
 - Standalone `ketatlas scaffold`, `serve <atlas.json>`, `audit`, and `validate` commands.
 - Basic, web and screenless process templates with a local configuration schema.
@@ -10,4 +26,4 @@
 - Canonical KetJS design system with pinned provenance and offline assets.
 - Static audits, CLI/server tests, browser evidence and packed-install verification.
 
-This entry describes the source version; it does not confirm publication to npm.
+Published to [npm](https://www.npmjs.com/package/ketatlas/v/0.1.0).

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 KETVIET JSC, Vietnam
+Copyright (c) 2026 KET VIET JSC, VN
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/NOTICE.md

@@ -1,6 +1,6 @@
 # Third-party notices
 
-KetAtlas is maintained by KETVIET JSC under the MIT license.
+KetAtlas is maintained by KET VIET JSC, VN under the MIT license.
 
 - The viewer originated from KétSuite's HTML flow-map prototype, then was extracted into this independent package. No mobile app code or business data is bundled.
 - Default tokens and UI primitives: `@ketvietlab/design-system` from [KetJS](https://github.com/ketvietlab/ketjs), MIT. Exact source revision and file hashes are recorded in `assets/design-system.lock.json`. Generated output only adapts root selectors to a Shadow DOM host; token values are unchanged. See `assets/KETJS-LICENSE`.

package/README.md

@@ -6,56 +6,48 @@ Turn a JSON file and your existing HTML screens into a canvas you can drag, zoom
 
 KetAtlas has an English UI, zero runtime npm dependencies, and no build step. Node.js **22+** is needed for the CLI. Viewers use native ES modules and run on an HTTP server.
 
-## Start from this repository
+## Demo
 
-```sh
-git clone git@github.com:ketvietlab/ketatlas.git
-cd ketatlas
-npm ci
-npm run dev
-```
+See a mobile workflow map in action: explore connected screens and try the HTML prototype.
+
+https://github.com/user-attachments/assets/13f24fc8-7b8e-4bda-9e02-364c120ee163
 
-Open **http://127.0.0.1:4178**. The playground includes mobile sign-in, a desktop approval flow, and a fulfilment process.
+## Run without a project install
 
-Create your own project:
+[KetAtlas is available on npm](https://www.npmjs.com/package/ketatlas). Use Node.js 22+ and run it from any directory:
 
 ```sh
-node bin/ketatlas.js scaffold ../my-atlas
-node bin/ketatlas.js serve ../my-atlas/atlas.json
-node bin/ketatlas.js audit ../my-atlas/atlas.json --strict
+npx --yes ketatlas@0.2.0 scaffold my-atlas --template web
+npx --yes ketatlas@0.2.0 serve my-atlas/atlas.json
+npx --yes ketatlas@0.2.0 audit my-atlas/atlas.json --strict
 ```
 
-No wrapper HTML is needed. Edit `atlas.json` and the files under `screens/`, then refresh the browser.
-
-## Run through npx
-
-Run immediately from a local checkout, including before the first push or npm release:
+Or install the CLI once for your user account:
 
 ```sh
-npx --yes --package ~/dev/ketatlas ketatlas scaffold my-atlas
-npx --yes --package ~/dev/ketatlas ketatlas serve my-atlas/atlas.json
-npx --yes --package ~/dev/ketatlas ketatlas audit my-atlas/atlas.json --strict
+npm install --global ketatlas@0.2.0
+ketatlas scaffold my-atlas
+ketatlas serve my-atlas/atlas.json
+ketatlas audit my-atlas/atlas.json --strict
 ```
 
-Replace `~/dev/ketatlas` with your checkout path. This uses the local package, not an npm registry release.
+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.
 
-Once the source has been pushed to GitHub, run without cloning it yourself:
+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.
 
-```sh
-npx --yes --package=github:ketvietlab/ketatlas ketatlas scaffold my-atlas
-npx --yes --package=github:ketvietlab/ketatlas ketatlas serve my-atlas/atlas.json
-npx --yes --package=github:ketvietlab/ketatlas ketatlas audit my-atlas/atlas.json
-```
+Edit the JSON and screen files, then refresh the browser. The default viewer address is **http://127.0.0.1:4178**.
 
-After `ketatlas` has been published to npm, the short form is:
+## Create mockups with an agent
+
+Install the KetAtlas skill in your product project:
 
 ```sh
-npx ketatlas scaffold my-atlas --template web
-npx ketatlas serve my-atlas/atlas.json
-npx ketatlas audit my-atlas/atlas.json --strict
+npx skills add ketvietlab/ketatlas --skill ketatlas
 ```
 
-The repository does not imply an npm release. Package installation is tested from the actual `.tgz` archive; release instructions are in [Releasing](docs/releasing.md).
+Ask your agent to use the skill with a product brief: requested flows, target platforms, design references, and output directory. The agent creates actual HTML screens, a version 1 `atlas.json`, and run instructions, then audits the result.
+
+See [Agent mockups](docs/agent-mockups.md) for installation options, a ready-to-use request, and a reusable brief template. Agents without skill support can read the [single skill file](skills/ketatlas/SKILL.md) directly.
 
 ## One file describes the journey
 
@@ -83,6 +75,10 @@ The repository does not imply an npm release. Package installation is tested fro
 
 URLs resolve relative to the JSON file. Nodes default to a left-to-right row. Set `column` and `row` for branches; set each screen's `viewport` for mobile or desktop dimensions. Reuse a screen in many flows without duplicating its HTML.
 
+## Track delivery
+
+Open **Screens** to filter screen progress, review blockers and edit acceptance checks with PR/test evidence. Records live in a sibling `atlas.progress.json` tracked in Git; repeated nodes share one screen record. A merged PR is not a verified screen. Local saves detect concurrent edits; static hosting is read-only. See [Screen progress](docs/progress.md) for the contract, CLI and embedding API.
+
 ## Commands
 
 | Command                 | Purpose                                                                                    |
@@ -109,6 +105,19 @@ Give the container a height. Ship `src/`, `styles/`, and `assets/` together. Sha
 
 ## Explore and contribute
 
+To develop KetAtlas itself, clone this repository and install its development dependencies:
+
+```sh
+git clone git@github.com:ketvietlab/ketatlas.git
+cd ketatlas
+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`.
+
+Stable version increases merged into `develop` are automatically published after CI verifies the package. See [Releasing](docs/releasing.md).
+
 - [Authoring guide](docs/authoring.md): screens, processes, branching, reuse, and viewport sizes.
 - [Configuration reference](docs/configuration.md): schema and defaults.
 - [CLI and audit](docs/cli.md): commands, exit codes, and audit boundaries.
@@ -127,4 +136,8 @@ npm run test:package
 
 Audit is static analysis. It does not execute product code or prove that native apps, external services, or embedded pages behave correctly. Arrows describe the authored workflow; the embedded HTML retains its own interactions.
 
-MIT · [Third-party notices](NOTICE.md).
+## License
+
+KetAtlas is a project of **KET VIET JSC, VN**, distributed under the [MIT License](LICENSE).
+
+Copyright (c) 2026 KET VIET JSC, VN. See [third-party notices](NOTICE.md) for bundled dependencies.

package/bin/audit.js

@@ -1,3 +1,4 @@
+import { readProgress, progressPath } from "./progress.js";
 import { readFile, realpath, stat } from "node:fs/promises";
 import { resolve, dirname, relative, sep, extname } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
@@ -93,6 +94,13 @@ export async function auditAtlas(file, { root: rootOption } = {}) {
     for (const f of config.flows)
       for (const n of f.nodes) if (n.url) await inspect(n.url, absolute, `node:${f.id}/${n.id}`);
   }
+  if (result.valid) {
+    try {
+      await readProgress(progressPath(absolute), config);
+    } catch (e) {
+      errors.push({ path: "progress", message: e.message });
+    }
+  }
   for (const url of remote)
     warnings.push({ path: "remote", message: `Remote URL not fetched: ${url}` });
   const flows = Array.isArray(config?.flows) ? config.flows : [];

package/bin/ketatlas.js

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
+import { progressPath, readProgress, saveProgress } from "./progress.js";
+import { summarizeProgress } from "../src/progress.js";
 import { readFile, readdir, mkdir, cp, writeFile, stat } from "node:fs/promises";
 import { resolve, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -13,6 +15,8 @@ const help = `KetAtlas — scaffold, serve, and audit HTML workflow maps
   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 --version
 
 Examples:
@@ -118,8 +122,58 @@ async function main(args) {
     );
     return;
   }
+  if (command === "progress") {
+    const { target, options } = parse(rest, {
+      json: "boolean",
+      init: "boolean",
+      set: "string",
+      record: "string",
+      expect: "string",
+    });
+    const file = resolve(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("; "));
+    const path = progressPath(file);
+    let result = await readProgress(path, atlas);
+    if (options.init) {
+      if (options.set || options.record || options.expect)
+        throw new Error("Use --init separately from an update.");
+      if (result.revision !== "missing") throw new Error("Progress already exists.");
+      result = await saveProgress(path, file, "missing", (data) => {
+        for (const s of atlas.screens || [])
+          Object.defineProperty(data.screens, s.id, {
+            value: { status: "unassessed" },
+            enumerable: true,
+          });
+        return data;
+      });
+    } else if (options.set || options.record || options.expect) {
+      if (!options.set || !options.record || !options.expect)
+        throw new Error("Updates need --set, --record and --expect from progress --json.");
+      const record = JSON.parse(await readFile(resolve(options.record), "utf8"));
+      result = await saveProgress(path, file, options.expect, (data) => {
+        Object.defineProperty(data.screens, options.set, {
+          value: { ...record, updatedAt: new Date().toISOString() },
+          enumerable: true,
+        });
+        return data;
+      });
+    }
+    const summary = summarizeProgress(result.data, atlas.screens || []);
+    console.log(
+      options.json
+        ? JSON.stringify({ ...result, summary }, null, 2)
+        : `${summary.total} screens · ${summary.counts.verified} verified · ${summary.blocked} blocked\nRevision: ${result.revision}\n${path}`,
+    );
+    return;
+  }
   if (command === "serve") {
-    const { target, options } = parse(rest, { port: "string", root: "string" }),
+    const { target, options } = parse(rest, {
+        port: "string",
+        root: "string",
+        "read-only": "boolean",
+      }),
       port = Number(options.port || 4178);
     if (!Number.isInteger(port) || port < 1 || port > 65535)
       throw new Error("Port must be 1–65535.");
@@ -128,7 +182,7 @@ async function main(args) {
       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 });
+      : await serveAtlas(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/bin/progress.js

@@ -0,0 +1,120 @@
+import { readFile, writeFile, rename, unlink, open, lstat } from "node:fs/promises";
+import { createHash, randomUUID } from "node:crypto";
+import { resolve } from "node:path";
+import { emptyProgress, requireProgress } from "../src/progress.js";
+export const progressPath = (file) => file.replace(/\.json$/i, "") + ".progress.json";
+const hash = (text) => createHash("sha256").update(text).digest("hex");
+export async function readProgress(file, atlas) {
+  try {
+    if ((await lstat(file)).isSymbolicLink())
+      throw new Error("Progress file must not be a symlink.");
+    const text = await readFile(file, "utf8");
+    return { data: requireProgress(JSON.parse(text), atlas), revision: hash(text) };
+  } catch (e) {
+    if (e.code !== "ENOENT") throw e;
+    return { data: emptyProgress(), revision: "missing" };
+  }
+}
+/** Shared by the CLI and local editor. One lock and content revision prevent stale writes. */
+export async function saveProgress(file, atlasFile, expected, change) {
+  file = resolve(file);
+  let lock;
+  try {
+    lock = await open(file + ".lock", "wx");
+  } catch (e) {
+    if (e.code === "EEXIST")
+      throw Object.assign(new Error("Another writer is saving. Reload and retry."), {
+        status: 409,
+      });
+    throw e;
+  }
+  const temp = file + "." + randomUUID() + ".tmp";
+  try {
+    const atlas = JSON.parse(await readFile(atlasFile, "utf8"));
+    const current = await readProgress(file, atlas);
+    if (!expected || expected !== current.revision)
+      throw Object.assign(
+        new Error(
+          "Progress changed since it was loaded. Reload before saving; your draft is still visible.",
+        ),
+        { status: 409 },
+      );
+    const data = requireProgress(change(structuredClone(current.data)), atlas);
+    const text = JSON.stringify(data, null, 2) + "\n";
+    await writeFile(temp, text, { flag: "wx" });
+    if ((await readProgress(file, atlas)).revision !== current.revision)
+      throw Object.assign(new Error("Progress changed during saving. Reload and retry."), {
+        status: 409,
+      });
+    await rename(temp, file);
+    return { data, revision: hash(text) };
+  } finally {
+    await unlink(temp).catch(() => {});
+    await lock.close();
+    await unlink(file + ".lock");
+  }
+}
+export function progressHandler(file, atlasFile, token, editable) {
+  const path = progressPath(file);
+  return async (req, res) => {
+    if (new URL(req.url, "http://localhost").pathname !== "/__ketatlas__/progress") return false;
+    const reply = (status, data) => {
+      res.writeHead(status, { "Content-Type": "application/json", "Cache-Control": "no-store" });
+      res.end(JSON.stringify(data));
+    };
+    try {
+      if (req.method === "GET") {
+        reply(200, {
+          ...(await readProgress(path, JSON.parse(await readFile(atlasFile, "utf8")))),
+          editable,
+        });
+        return true;
+      }
+      if (req.method !== "PUT") {
+        reply(405, { error: "Method not allowed" });
+        return true;
+      }
+      const origin = `http://${req.headers.host}`;
+      if (
+        !editable ||
+        req.headers.origin !== origin ||
+        req.headers["x-ketatlas-token"] !== token ||
+        !req.headers["content-type"]?.startsWith("application/json")
+      ) {
+        reply(403, { error: "Progress writes require the local editor." });
+        return true;
+      }
+      let text = "",
+        size = 0;
+      for await (const chunk of req) {
+        size += chunk.length;
+        if (size > 1024 * 1024) {
+          reply(413, { error: "Progress update is too large." });
+          return true;
+        }
+        text += chunk;
+      }
+      const body = JSON.parse(text);
+      if (
+        typeof body.screenId !== "string" ||
+        !body.record ||
+        typeof body.record !== "object" ||
+        Array.isArray(body.record)
+      )
+        throw new Error("Expected a screen ID and record.");
+      const result = await saveProgress(path, atlasFile, req.headers["if-match"], (data) => {
+        Object.defineProperty(data.screens, body.screenId, {
+          value: { ...body.record, updatedAt: new Date().toISOString() },
+          enumerable: true,
+          writable: true,
+          configurable: true,
+        });
+        return data;
+      });
+      reply(200, { ...result, editable });
+    } catch (e) {
+      reply(e.status || 400, { error: e.message });
+    }
+    return true;
+  };
+}

package/bin/server.js

@@ -21,7 +21,7 @@ const within = (root, path) => {
 /** Local static preview only. Resolves symlinks before checking the root boundary. */
 export async function serve(
   directory,
-  { port = 4178, host = "127.0.0.1", viewer, packageRoot } = {},
+  { port = 4178, host = "127.0.0.1", viewer, packageRoot, handler } = {},
 ) {
   const root = await realpath(resolve(directory));
   if (!(await stat(root)).isDirectory()) throw new Error("Serve root must be a directory.");
@@ -30,6 +30,7 @@ export async function serve(
       res.writeHead(status, { "Content-Type": "text/plain; charset=utf-8" });
       res.end(message);
     };
+    if (handler && (await handler(req, res))) return;
     if (!["GET", "HEAD"].includes(req.method)) return fail(405, "Method not allowed");
     try {
       const pathname = decodeURIComponent(new URL(req.url, "http://localhost").pathname);

package/bin/viewer.js

@@ -1,3 +1,5 @@
+import { randomBytes } from "node:crypto";
+import { progressHandler } from "./progress.js";
 import { readFile, realpath, stat } from "node:fs/promises";
 import { resolve, dirname, relative, sep } from "node:path";
 import { validateAtlas, AtlasValidationError } from "../src/config.js";
@@ -15,6 +17,12 @@ export async function serveAtlas(file, options = {}) {
   if (rel === ".." || rel.startsWith(".." + sep) || rel.startsWith(sep))
     throw new Error("The JSON file must be inside --root.");
   const configURL = "/" + rel.split(sep).map(encodeURIComponent).join("/");
-  const html = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>KetAtlas</title><style>html,body{margin:0;height:100%}#atlas{height:100dvh}#error{font:16px system-ui;padding:24px;white-space:pre-wrap}</style></head><body><main id="atlas"></main><pre id="error" hidden></pre><script type="module">import {loadAtlas} from '/__ketatlas__/src/index.js';try{window.atlas=await loadAtlas(document.querySelector('#atlas'),${JSON.stringify(configURL).replaceAll("<", "\\u003c")},{syncUrl:true});document.title=${JSON.stringify(config.title).replaceAll("<", "\\u003c")}+' · KetAtlas';}catch(error){const el=document.querySelector('#error');el.hidden=false;el.textContent=error.message;}</script></body></html>`;
-  return serve(root, { ...options, viewer: html, packageRoot });
+  const token = randomBytes(24).toString("hex");
+  const html = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>KetAtlas</title><style>html,body{margin:0;height:100%}#atlas{height:100dvh}#error{font:16px system-ui;padding:24px;white-space:pre-wrap}</style></head><body><main id="atlas"></main><pre id="error" hidden></pre><script type="module">import {loadAtlas} from '/__ketatlas__/src/index.js';try{window.atlas=await loadAtlas(document.querySelector('#atlas'),${JSON.stringify(configURL).replaceAll("<", "\\u003c")},{syncUrl:true,progressEndpoint:"/__ketatlas__/progress",progressToken:${JSON.stringify(token)}});document.title=${JSON.stringify(config.title).replaceAll("<", "\\u003c")}+' · KetAtlas';}catch(error){const el=document.querySelector('#error');el.hidden=false;el.textContent=error.message;}</script></body></html>`;
+  return serve(root, {
+    ...options,
+    viewer: html,
+    packageRoot,
+    handler: progressHandler(absolute, absolute, token, !options.readOnly),
+  });
 }

package/docs/agent-mockups.md

@@ -0,0 +1,85 @@
+# Create mockups with an agent
+
+Give an agent the KetAtlas skill and a product brief. The agent produces real HTML screens plus `atlas.json`; KetAtlas opens those files as an interactive workflow map. The brief describes the product, while the generated JSON schema and CLI audit check the output format.
+
+## Install the skill once
+
+From the project in which you want to create mockups:
+
+```sh
+npx skills add ketvietlab/ketatlas --skill ketatlas
+```
+
+Choose your agent when prompted, or target it directly:
+
+```sh
+npx skills add ketvietlab/ketatlas --skill ketatlas --agent codex
+npx skills add ketvietlab/ketatlas --skill ketatlas --agent claude-code
+```
+
+These commands use the separate [open agent skills CLI](https://github.com/vercel-labs/skills). Installation is project-scoped by default. The skill is a single portable [SKILL.md](../skills/ketatlas/SKILL.md), not a new KetAtlas command or a hosted generation service.
+
+If the agent does not support skill installation, attach that file or ask it to read [the skill on GitHub](https://github.com/ketvietlab/ketatlas/blob/develop/skills/ketatlas/SKILL.md) before working. Installing a skill does not require changing the product repository's runtime dependencies.
+
+## Ask for a mockup
+
+For a short request, invoke the skill and include the product, target, design reference, and flows:
+
+```text
+Use $ketatlas to create one shared HTML mobile prototype for Northstar Tasks
+in ./tasks/mobile. Use 390 × 844 screens, English product copy, and the design
+system in ./design-system. Include sign-in, password recovery, task list,
+task details, and task completion. Map entry points, actions, outcomes, and
+relevant error/recovery states. Implement the main interactions, then audit
+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 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.
+
+## 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`.
+
+```markdown
+# Mockup brief
+
+- Product and audience:
+- User goal:
+- Output directory:
+- Target platforms and viewport sizes:
+- Product content language:
+- Design system, 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:
+- Scope exclusions and any intentional remote dependencies:
+
+## Expected delivery
+
+Create actual HTML screens and one KetAtlas version 1 atlas.json. Reuse
+screens and styles across flows. Set explicit flow starts, outcomes, and
+labelled transitions. Each named screen state must open directly.
+
+Use the generated ketatlas.schema.json. Run KetAtlas audit, test the
+important interactions in the viewer when browser automation is available,
+and report results or limitations. Include a README with run commands,
+flow coverage, demo inputs, and assumptions. Keep the output free of package
+manifests, lockfiles, local dependencies, and copied viewer/test tooling.
+```
+
+For an existing prototype, ask the agent to reuse its HTML and add or update the atlas instead of rebuilding it. For later changes, name the flow or screen IDs to preserve, for example: **“Add an expired-code recovery branch to sign-in; keep existing screen IDs and audit the updated project.”**
+
+## Review the result
+
+```sh
+npx ketatlas serve ./tasks/mobile/atlas.json
+npx ketatlas audit ./tasks/mobile/atlas.json --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.

package/docs/architecture.md

@@ -1,6 +1,6 @@
 # Architecture
 
-KetAtlas is a static browser viewer plus a Node.js command-line toolkit. There is no database, account service, application backend, or runtime npm dependency.
+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
@@ -15,6 +15,12 @@ atlas.json + screen HTML
                        └── lazy HTML iframes + interactive inspector
 ```
 
+## 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.
+
+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.
+
 ## Ownership
 
 | Directory         | Responsibility                                                |
@@ -55,3 +61,7 @@ The default theme uses Inter and KetJS's canonical tokens and primitives. `prepa
 ## Version 1 boundaries
 
 KetAtlas is a viewer and authoring toolkit, not a visual graph editor. Users edit JSON and HTML in their normal tools. It does not record a graph by watching clicks, synthesize screens, calculate backend permissions, or execute the arrow graph as an automated test. Cross-flow edges, collaborative editing and browser-based project audits are outside the current contract.
+
+## Delivery tracking
+
+`src/progress.js` owns progress validation and unique-screen counts. `src/progress-ui.js` owns the screen register and progress editor. `bin/progress.js` shares a locked, revision-checked atomic writer between CLI and local HTTP updates. Progress does not alter graph layout or infer completion from PR state. See [Screen progress](progress.md).

package/docs/cli.md

@@ -1,6 +1,8 @@
 # CLI reference
 
-Use `ketatlas` after installing the package, `node /path/to/ketatlas/bin/ketatlas.js` from a checkout, or the npx forms in the [README](../README.md).
+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.
+
+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
 
@@ -68,3 +70,7 @@ ketatlas --help
 ```
 
 `validate` checks configuration and graph references only. It is also available as `validateAtlas(data)` in JavaScript. JSON Schema supports editor completion; graph-reference and URL safety checks belong to the runtime validator and audit.
+
+## 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.

package/docs/configuration.md

@@ -63,3 +63,7 @@ A node without `screen` defaults to `note` and requires a title. Use `type: "ext
 `from`, `to` and a nonempty `label` are required. Endpoints reference node IDs in the same flow. `kind` is `primary` (default), `conditional`, or `recovery`. Arrows are orthogonal and labels describe the action or condition.
 
 Cross-flow edges are not part of version 1. Reuse the destination screen in another flow, or add an external/note handoff to explain the boundary. Start and outcome markers express authored intent; clicking them does not invoke a backend operation.
+
+## Delivery progress
+
+Delivery records use the optional sibling `<atlas-name>.progress.json`, with `progress.schema.json` and semantic validation, rather than extra properties in the version 1 workflow. See [Screen progress](progress.md).

package/docs/integration.md

@@ -106,3 +106,7 @@ Iframe previews are sandboxed. Scripts and forms work by default, but the page h
 Remote pages can reject framing using CSP or `X-Frame-Options`. KetAtlas cannot override that. Use a permitted embedded route or the **Open in new tab** action. Test links/forms with the default sandbox before sharing a project.
 
 The viewer uses native dialog, Shadow DOM, ResizeObserver, container queries and modern CSS. Chromium is covered by the browser suite. Other modern engines should be qualified against your host application before promising support.
+
+## Progress adapters
+
+`createAtlas` accepts `options.progress`. `loadAtlas` discovers a sibling progress JSON or accepts `progressURL`. Both support `progressRevision`, `saveProgress(screenId, record, revision)` and `reloadProgress()`; adapters return `{data, revision}`. No save adapter means read-only. See [Screen progress](progress.md).

package/docs/migration.md

@@ -30,6 +30,7 @@ Keep the existing screen IDs. Give repeated states unique node IDs, but reuse th
 3. Set the default viewport to 390 × 844. Keep DOC/TARGET source labels if useful to reviewers.
 4. Run `ketatlas audit atlas.json --root <project-root>` and resolve diagnostics.
 5. Run `ketatlas serve atlas.json --root <project-root>` and compare the existing 22 journeys, 108 screen IDs, and 162 edges against the exported graph.
-6. Re-run the project's browser interactions under the iframe sandbox. Only enable additional sandbox permissions for trusted HTML when its behavior requires them.
+6. Recheck product interactions with external browser tooling under the default iframe sandbox; use portable HTML rather than weakening the sandbox.
+7. Remove the old viewer tooling, package manifest, lockfile, and local build/test dependencies from the atlas folder. Keep screen HTML/CSS/JavaScript and its assets. Use global or version-pinned npx commands for serving and auditing. Record any earlier browser reports as historical evidence rather than requiring the old harness to run the map.
 
 KetAtlas UI is English. Vietnamese business labels inside the project's configuration and HTML can remain Vietnamese.