ketatlas 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,6 +1,15 @@
 # Changelog
 
-## 0.1.0 — Initial scaffold
+## 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 +19,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.1.1 scaffold my-atlas --template web
+npx --yes ketatlas@0.1.1 serve my-atlas/atlas.json
+npx --yes ketatlas@0.1.1 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.1.1
+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. `serve` and `audit` leave project files unchanged unless an audit output file is explicitly requested.
 
-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**.
+
+## Create mockups with an agent
 
-After `ketatlas` has been published to npm, the short form is:
+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
 
@@ -109,6 +101,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 +132,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/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

@@ -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                                                |

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
 

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.

package/docs/releasing.md

@@ -1,8 +1,34 @@
 # Releasing KetAtlas
 
-The npm package name and executable are both **ketatlas**. The package is ESM, includes TypeScript declarations, and ships the CLI, viewer modules, styles, fonts, licenses, schema and templates. Development dependencies, examples, test results and the sibling mobile project are not required at runtime.
+The npm package and executable are both **ketatlas**. Releases come from `develop` and use the stable `latest` distribution tag.
 
-## Verify the exact package
+## One-time setup
+
+Add a GitHub Actions repository secret named **NPM_PUBLISH_TOKEN** in **Settings → Secrets and variables → Actions**. Use an npm granular access token with package **Read and write** permissions for `ketatlas` and **Bypass two-factor authentication** enabled. Keep its expiry current. The local `.env.local` file is ignored by Git and is never loaded by CI.
+
+Only the publish step receives the token. Pull requests, verification, and registry checks do not receive it. The publish job also requests an OIDC identity to attach npm provenance; publishing authentication uses the repository secret. See [GitHub's npm publishing guide](https://docs.github.com/en/actions/tutorials/publish-packages/publish-nodejs-packages).
+
+## Release through develop
+
+On your feature branch, bump the package and lockfile together:
+
+```sh
+npm version patch --no-git-tag-version
+```
+
+Use `minor` or `major` when appropriate. Move the relevant changelog entries under the new version, commit both version files with the changes, and merge the pull request into `develop`.
+
+The [CI workflow](../.github/workflows/ci.yml) runs on pull requests and branch pushes. Automatic publishing runs on pushes to `develop`, including merge commits, squash merges, and direct pushes. An explicit workflow dispatch on `develop` can retry an unpublished release after a workflow fix:
+
+1. Formatting, configuration audits, unit tests, browser tests, and a packed-install test must pass.
+2. The version must increase from `package.json` at the push event's previous commit. The lockfile must agree. Automatic releases accept stable `major.minor.patch` versions; prereleases fail with an explanation.
+3. The version must be absent from npm and greater than npm's current `latest`. An unchanged or already published version is skipped. Version decreases, registry failures, and mismatched version files fail the job.
+4. The publish job downloads and publishes the exact `.tgz` archive that passed the packed-install test, with public access and provenance.
+5. CI checks that the version is visible on npm and records the result in the workflow summary.
+
+Publish jobs are queued and run one at a time. The npm check happens after entering the queue, so an older run cannot move `latest` backwards. The first push creating `develop` has no previous commit; it uses the npm comparison instead. Pushing the existing `0.1.0` release therefore skips publication.
+
+## Verify locally
 
 ```sh
 npm ci
@@ -13,28 +39,31 @@ npm run format:check
 npm pack --dry-run
 ```
 
-The package test creates a real archive, invokes its CLI through `npm exec` without a registry lookup, scaffolds a project outside the repository, audits it, and starts its JSON viewer. This catches missing files and accidental reliance on a maintainer checkout.
+The package test creates a real archive, invokes its CLI through `npm exec` without a registry lookup, scaffolds a project outside the repository, audits it, and starts its JSON viewer. This catches missing files and reliance on a maintainer checkout.
 
-## Publish
+## Retry a failed release
 
-An npm release is an explicit maintainer action. Confirm npm ownership of the unscoped `ketatlas` name and authenticate with an account allowed to publish it. Do not put credentials in repository files.
-
-For interactive publishing, [configure two-factor authentication on your npm account](https://docs.npmjs.com/configuring-two-factor-authentication/) and complete the verification requested during publication. A successful `npm whoami` confirms login but does not guarantee that publishing authentication requirements are met. Keep recovery codes and credentials private.
+For a missing or expired repository secret, fix the secret and rerun the failed workflow. If the workflow itself needed a fix in a later commit, dispatch the updated workflow on `develop` with the **previous commit SHA from the original failed release push**:
 
 ```sh
-npm whoami
-npm publish --access public
+gh workflow run ci.yml --ref develop -f before_sha=<original-40-character-before-sha>
 ```
 
-Bump `package.json` and `package-lock.json` together before subsequent releases, record the change in `CHANGELOG.md`, and tag the released commit. A Git push alone does not publish npm. The CI workflow verifies pushes and pull requests; it does not publish automatically.
+The supplied SHA must be an ancestor of the checked-out release commit. The version must still increase from that baseline, all verification runs again, and npm must not already contain that version. This retry uses the same tested archive and provenance path; it does not disable release gates.
+
+If npm already accepted the version, the rerun skips publication. Check npm before changing the version after a timeout: a publish may have succeeded even if the final visibility check failed.
 
-After publishing, verify the registry distribution outside the checkout:
+Do not reuse a published version for changed package contents. Bump the version again for the next release. A failed verification must be fixed and all checks rerun before publishing.
+
+After a successful release, verify outside the checkout with the released version:
 
 ```sh
-npx ketatlas@0.1.0 --version
-npx ketatlas@0.1.0 scaffold /tmp/ketatlas-release-check
-npx ketatlas@0.1.0 audit /tmp/ketatlas-release-check/atlas.json --strict
-npx ketatlas@0.1.0 serve /tmp/ketatlas-release-check/atlas.json
+npx ketatlas@0.1.1 --version
+npx ketatlas@0.1.1 scaffold /tmp/ketatlas-release-check
+npx ketatlas@0.1.1 audit /tmp/ketatlas-release-check/atlas.json --strict
+npx ketatlas@0.1.1 serve /tmp/ketatlas-release-check/atlas.json
 ```
 
-Before publication, use `npx --yes --package=github:ketvietlab/ketatlas ketatlas ...` or a local `.tgz` archive. Pin a commit or released version for reproducible team workflows.
+## Token maintenance
+
+GitHub Actions secrets do not refresh when a local token changes. Replace the repository secret before the token expires. npm has announced changes to direct publishing with bypass-2FA tokens targeted for January 2027; migrate publishing authentication to [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/) before that change takes effect. See the [npm announcement](https://github.blog/changelog/2026-07-31-restricting-npm-bypass-2fa-granular-access-tokens/).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ketatlas",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Interactive HTML maps for screens, workflows, and user journeys.",
   "type": "module",
   "license": "MIT",
@@ -33,6 +33,7 @@
     "LICENSE",
     "NOTICE.md",
     "templates",
+    "skills",
     "docs",
     "CHANGELOG.md"
   ],
@@ -42,8 +43,8 @@
     "test": "node --test tests/*.test.js",
     "test:e2e": "node tests/browser.mjs",
     "check": "npm run validate && npm test && npm run test:e2e",
-    "format": "prettier --write src styles/ketatlas.css bin scripts docs examples starter templates tests '*.md' '*.json' .github/workflows",
-    "format:check": "prettier --check src styles/ketatlas.css bin scripts docs examples starter templates tests '*.md' '*.json' .github/workflows",
+    "format": "prettier --write src styles/ketatlas.css bin scripts docs examples starter templates skills tests '*.md' '*.json' .github/workflows",
+    "format:check": "prettier --check src styles/ketatlas.css bin scripts docs examples starter templates skills tests '*.md' '*.json' .github/workflows",
     "prepare:assets": "node scripts/prepare-assets.mjs",
     "prepack": "node scripts/verify-assets.mjs",
     "prepare:templates": "node scripts/schema.mjs && node scripts/prepare-templates.mjs",

package/skills/ketatlas/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: ketatlas
+description: Create or update interactive HTML mockups and workflow maps in KetAtlas format. Use when a user requests KetAtlas output, an atlas.json project, or draggable flows connecting real HTML screens; also use to scaffold, serve, or audit an existing atlas.
+---
+
+# 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.
+
+## Read the brief and choose the scope
+
+Use the user's requirements, existing project files, and design references to determine:
+
+- Product, audience, requested flows, and the goal of each flow.
+- Platform and viewport: mobile, web, mixed screens, or a process without screens.
+- Design system and product content language. KetAtlas's own viewer is English; authored content can use the requested language.
+- Output directory, existing screens to reuse, and the intended depth of interaction.
+
+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.
+
+## Scaffold or extend
+
+Node.js 22 or newer is required. For a new, empty destination:
+
+```sh
+npx --yes ketatlas scaffold ./tasks/mockups --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.
+
+A self-contained project typically has:
+
+```text
+tasks/mockups/
+  atlas.json
+  ketatlas.schema.json
+  screens/                 HTML pages and shared CSS/JavaScript
+  styles/                  Starter design assets, when used
+  README.md                Run commands, flow coverage, assumptions, verification
+```
+
+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.
+
+## Model the journey
+
+Sketch the requested flow inventory before implementing screens: start, user action, condition, destination, and outcome. Include the relevant success, validation, empty, loading, error, and recovery states supported by the brief; do not multiply every screen into states that have no meaning for that product.
+
+Use the generated `ketatlas.schema.json` as the field reference. `version: 1` is the atlas format version, not the npm package version. Unknown properties are rejected. Store requirements, coverage notes, and backlog items in Markdown rather than inventing JSON fields.
+
+Core rules:
+
+- Register each reusable screen once in `screens` with `id`, `title`, and `url`. Paths resolve relative to `atlas.json`.
+- Give each flow an `id`, `title`, nonempty `nodes`, and `edges`. Set `start` and `ends` explicitly when authoring a journey so entry and outcomes are unambiguous.
+- A screen node references a screen ID. A repeated occurrence gets a new node ID and may override `url`, for example `./screens/sign-in.html?state=invalid`.
+- For a decision or off-screen operation, use a node with `type: "note"`, `title`, and optionally `description`. Use `type: "external"` for a handoff. There is no `decision` node type.
+- Edges require `from`, `to`, and a nonempty `label` describing the action or condition. `kind` is `primary`, `conditional`, or `recovery`.
+- Edge endpoints, `start`, and `ends` reference node IDs within the same flow. Cross-flow edges are unsupported; reuse the destination screen or explain the handoff with a note.
+- IDs start with a letter or digit and contain only letters, digits, dots, underscores, or hyphens. Screen and flow IDs are unique across the atlas; node IDs are unique within their flow.
+- Set `column` and `row` explicitly for branches. Both are integers from 0 to 100; no two nodes in a flow share a cell. This is a grid, not an automatic graph layout engine.
+- Set the atlas `viewport` or a screen override to the intended layout size. The mobile default is 390 × 844; choose desktop dimensions from the brief. Width and height are integers from 160 to 4096.
+
+Example structure, to adapt to the actual product and HTML files:
+
+```json
+{
+  "$schema": "./ketatlas.schema.json",
+  "version": 1,
+  "title": "Account access",
+  "viewport": { "width": 390, "height": 844 },
+  "screens": [
+    { "id": "sign-in", "title": "Sign in", "url": "./screens/sign-in.html" },
+    { "id": "home", "title": "Home", "url": "./screens/home.html" }
+  ],
+  "flows": [
+    {
+      "id": "sign-in",
+      "title": "Sign in",
+      "start": "entry",
+      "ends": ["success"],
+      "nodes": [
+        { "id": "entry", "screen": "sign-in", "column": 0, "row": 0 },
+        {
+          "id": "invalid",
+          "screen": "sign-in",
+          "title": "Invalid credentials",
+          "url": "./screens/sign-in.html?state=invalid",
+          "column": 1,
+          "row": 1
+        },
+        { "id": "success", "screen": "home", "column": 2, "row": 0 }
+      ],
+      "edges": [
+        { "from": "entry", "to": "success", "label": "Credentials accepted" },
+        {
+          "from": "entry",
+          "to": "invalid",
+          "label": "Credentials rejected",
+          "kind": "conditional"
+        },
+        { "from": "invalid", "to": "entry", "label": "Try again", "kind": "recovery" }
+      ]
+    }
+  ]
+}
+```
+
+## Build the actual screens
+
+Make each screen a complete HTML document with a viewport meta tag and `body { margin: 0; }`. Keep product content padding, but do not wrap the page in a second phone bezel, presentation frame, reviewer sidebar, or outer mockup margin. The iframe is the screen boundary.
+
+Use shared CSS/components and deterministic mock data. States referenced by node URLs must render directly when opened or refreshed, without requiring a previous login or click. Implement the relevant buttons, forms, validation feedback, and navigation in HTML/JavaScript: graph arrows do not wire screen interactions automatically.
+
+The default iframe sandbox allows scripts and forms but gives the page an opaque origin. Prefer ordinary links, classic scripts, inline mock data, URL parameters, and in-memory state for portable prototypes. Storage, authenticated fetch, and some module imports can fail in this sandbox. Test in **Try this screen**, not just a standalone tab; do not solve a prototype issue by weakening the viewer's sandbox.
+
+## Validate and hand off
+
+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
+```
+
+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.
+
+For local projects, fix structural errors, missing assets, and unreachable nodes until strict audit passes. Remote screen/assets URLs produce warnings and are not fetched by audit: when those are intentional, run the normal audit, report the warnings, and verify embedding separately rather than claiming a strict pass. With `audit --json --strict`, check the exit status and warnings as well as `valid`.
+
+When browser automation is available, inspect the map and actual HTML at the declared viewport. Exercise each requested flow's primary route and relevant recovery route, and check for console errors and accidental clipping. Audit alone does not prove interaction, appearance, or complete coverage. If browser verification is unavailable, state that limit and still deliver the auditable files.
+
+Update the project's README with flow-to-screen/state coverage, assumptions, demo inputs, and run commands. Return the output location, the serve command or live preview URL, audit results, and any remaining limitations. Do not claim that a mockup implements production APIs or native application behavior.

package/templates/basic/README.md

@@ -7,7 +7,7 @@ npx ketatlas serve atlas.json
 npx ketatlas audit atlas.json --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 or build step is needed.
+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.1.1 and use ketatlas serve atlas.json.
 
 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.
 

package/templates/process/README.md

@@ -7,7 +7,7 @@ npx ketatlas serve atlas.json
 npx ketatlas audit atlas.json --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 or build step is needed.
+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.1.1 and use ketatlas serve atlas.json.
 
 This template models a process without HTML screens. Add a screen registry and screen nodes when needed.
 

package/templates/web/README.md

@@ -7,7 +7,7 @@ npx ketatlas serve atlas.json
 npx ketatlas audit atlas.json --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 or build step is needed.
+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.1.1 and use ketatlas serve atlas.json.
 
 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.