kaloko 0.15.0 → 0.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kaloko",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Your AI agents build; Kaloko walks every screen, puts it on one canvas and records who approved what.",
   "keywords": [
     "qa",

package/schemas/config.v1.json

@@ -8,7 +8,9 @@
   "properties": {
     "schema": { "const": "qawalk.config.v1" },
     "org": { "type": "string", "description": "Organization slug on kaloko.app." },
-    "project": { "type": "string" },
+    "project": { "type": "string", "description": "Slug of the Kaloko project runs of this repository belong to (a scenario's project: wins)." },
+    "project_name": { "type": "string", "maxLength": 80, "description": "The name people see for that project on Kaloko (ECO Podcasty). A share creates a missing project with it; kaloko projects sync renames an existing one." },
+    "product": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{0,79}$", "description": "Slug of a product on Kaloko the project is part of; kaloko projects sync adds the project to it." },
     "products": {
       "type": "object",
       "description": "Optional: what is released and versioned as a whole and has its own visual changelog (docs/DOCS-CHANGELOG.md). Without it the project is the product. Keys are product slugs.",

package/schemas/run.v1.json

@@ -281,6 +281,10 @@
         "slug": {
           "type": "string"
         },
+        "name": {
+          "type": "string",
+          "description": "The project's name from project_name: in kaloko.config.yml; a project that a share creates gets it."
+        },
         "repo": {
           "type": [
             "string",

package/schemas/scenario.v1.json

@@ -373,6 +373,24 @@
           "description": "Regions left out of pixel comparisons (clocks, ads, carousels): a selector, or a rectangle in page pixels of one viewport. kaloko stability suggests them.",
           "items": { "$ref": "#/$defs/ignoreRegion" }
         },
+        "details": {
+          "type": "array",
+          "maxItems": 20,
+          "description": "Named details for user guides and docs: one element in the part of the page around it (its section or card), outlined, captured in every locale and viewport. Docs show one with ![…](kaloko:<scenario>/<step>#<id>).",
+          "items": {
+            "type": "object",
+            "required": ["id", "name", "selector"],
+            "additionalProperties": false,
+            "properties": {
+              "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,59}$", "description": "Stable id, used in docs references (#add-to-cart) and file names." },
+              "name": { "$ref": "#/$defs/localized", "description": "What the reader looks at, e.g. \"Add to cart button\"; one text or one per locale." },
+              "selector": { "type": "string", "minLength": 1, "description": "CSS selector of the element; the first match is outlined." },
+              "context": { "type": "string", "minLength": 1, "description": "How much of the page around it: section (the nearest section or landmark), card (the nearest card, list item or framed box), page (one screen around it) or a CSS selector of an ancestor. Default: the nearest section or card at least 480 × 240 px, at most one screen." },
+              "padding": { "type": "integer", "minimum": 0, "maximum": 200, "description": "Pixels of page around the context (default 16)." },
+              "states": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,39}$" }, "description": "Step states to take it in (default: every state the step is captured in)." }
+            }
+          }
+        },
         "items": {
           "type": "object",
           "additionalProperties": false,

package/skills/kaloko/SKILL.md

@@ -26,9 +26,9 @@ description: >
   Clef triage findings (experimental) to read, mention or answer, when
   a run's health (the advisory checks of packs: SEO, accessibility,
   performance, console) should be checked, fixed or adopted into acceptance,
-  and when a team's own repository turns runs into regulated documentation
-  (requirement refs, kaloko evidence, the evidence package, the evidence.ready
-  webhook).
+  and when a team's own repository turns runs into quality evidence for its
+  QMS or GxP (requirement refs, kaloko evidence, the evidence package, the
+  evidence.ready webhook).
 ---
 
 # Kaloko
@@ -89,7 +89,9 @@ verdict), and run `kaloko prune` without `--yes` to see what a clean-up would do
 Draft and edit the Unreleased section of the changelog (`kaloko changelog draft
 --apply`) and add step references to it and to guides. Put the products of the
 config on Kaloko (`kaloko products sync`: it records no release) and list them
-(`kaloko products list`). Write, translate and fix
+(`kaloko products list`). Create the project the config names
+(`kaloko projects sync` or `kaloko projects create` with the name the person
+gave). Write, translate and fix
 guides in the docs folder, run `kaloko docs check`, and export them for a docs
 site (`kaloko export docs --format …`) into a local folder.
 
@@ -105,6 +107,9 @@ design reference or baseline, merging a design branch, keeping your version of
 a step in a sync conflict (`--mine`), turning on `html_view`, turning on recordings for
 a whole project (`capture.record` in the config: storage), a real clean-up
 (`kaloko prune --yes`), trashing someone else's run, archiving a scenario,
+renaming a project or restricting it (`kaloko projects rename`, a `kaloko
+projects sync` that would rename), picking one site of a repository that
+holds several (ask which one before `kaloko init` or a walk),
 recording a release (`kaloko release`) or asking to publish a changelog,
 publishing docs (`kaloko docs publish`, `--reviewed` above all: it says a
 person checked the text), writing a release workflow (`kaloko ci github
@@ -125,7 +130,11 @@ only when a person says that value may be uploaded.
 
 - A new project or an organization without runs of its own (install, sign in,
   the sample run, the first flow from a URL or a task, share, point the person
-  to the canvas): [reference/first-run.md](reference/first-run.md)
+  to the canvas), and naming the project on Kaloko (`project_name:`,
+  `kaloko projects create|rename|sync`): [reference/first-run.md](reference/first-run.md)
+- A repository with several sites or apps (monorepo, Rails engines, Folio
+  sites): ask which one, then `kaloko init --site … --base-url …`:
+  [reference/first-run.md#several-sites-in-one-repository](reference/first-run.md#several-sites-in-one-repository)
 - Writing or updating the plan and scenario: [reference/acceptance.md](reference/acceptance.md)
 - Android, iOS (Simulator or a real iPhone), Electron, macOS and Windows apps,
   several devices of one app, WebViews inside apps, or screens captured by
@@ -169,8 +178,9 @@ only when a person says that value may be uploaded.
   [reference/collaboration.md](reference/collaboration.md)
 - Reading runs, feedback and the inbox over MCP instead of the CLI:
   [reference/mcp.md](reference/mcp.md)
-- Evidence for regulated work (GxP): requirement `refs:`, `kaloko evidence`,
-  the evidence package and its check, the `evidence.ready` webhook, feeding a
+- Quality evidence for a team's QMS (ISO 9001, ISO 13485, IEC 62304, ISO 27001;
+  GxP is the strictest case): requirement `refs:`, `kaloko evidence`, the
+  evidence package and its check, the `evidence.ready` webhook, feeding a
   team's own document templates, signatures and what an agent must never do:
   [reference/evidence.md](reference/evidence.md)
 - Filing a returned step or a failing criterion in Jira or Linear, issue keys in

package/skills/kaloko/reference/acceptance.md

@@ -97,8 +97,10 @@ English words; one plain word such as a brand name is left alone).
   reader announces). `HC313` landmarks (one `main`, labelled repeats) and
   `HC314` ARIA (unknown roles and attributes, references to missing ids,
   `aria-hidden` over focusable content) are read from the page. The first
-  five focus stops are kept as screenshots and the canvas can draw the tab
-  order on the capture. The walk only moves focus: nothing is clicked or
+  five focus stops are kept as screenshots (step attachments of kind
+  `focus`, "Keyboard focus · HC309" on the canvas, linked to the check; the
+  Health tab shows them under `HC309` and in the tab order) and the canvas
+  can draw the tab order on the capture. The walk only moves focus: nothing is clicked or
   typed, and the page is left unfocused at the top. Stack steps walk the
   keyboard on their first five pages. Still a subset of WCAG 2.2 AA; it
   does not replace an audit with a screen reader.

package/skills/kaloko/reference/docs.md

@@ -14,6 +14,7 @@ A picture in Markdown names a step instead of a PNG file:
 ![Payment](kaloko:checkout/payment?version=prev)          the release before the one this entry belongs to
 ![Payment](kaloko:checkout/payment?locale=cs&viewport=mobile&state=dark)
 ![Payment](kaloko:checkout/payment?media=video)           the step's recording plays on the picture
+![Pay](kaloko:checkout/payment#pay-button)                a named detail of the step (details: in the scenario)
 ![Payment](kaloko:payment)                                a step of the product's default_scenario
 ```
 
@@ -28,6 +29,29 @@ a dialog, a language switch), not for every step. Check a reference with MCP `re
 `GET /api/v1/orgs/<org>/steps/resolve?ref=…`: it answers the signed image URL (and `video` with `mp4`, `webm` and `duration_ms` when it plays), the run and how the version was found
 (`release`, `app_version`, `reference_env`, `accepted`; `exact: false` means a fallback).
 
+## Details for guides
+
+When a guide talks about one control, show that control in its part of the page instead of the whole screen. Declare
+it on the step in the scenario and refer to it with `#<id>`:
+
+```yaml
+details:
+  - id: pay-button                                   # letters, digits, - and _; used in references and file names
+    name: { en: Pay button, cs: Tlačítko Zaplatit }  # one text or one per locale
+    selector: "#pay"                                 # the first match is outlined
+    context: card                                    # optional: section | card | page | a CSS selector of an ancestor
+    padding: 24                                      # optional, px around the context (default 16)
+    states: [error]                                  # optional: only in these states of the step
+```
+
+Without `context` the picture is the nearest section, landmark or card around the element that is at least
+480 × 240 px (90 % of the width on a phone), at most one screen around the element, with a ring drawn around the
+element. Every walk takes each detail in every locale and viewport, masked like the screenshot, as an attachment of
+kind `detail` (canvas: Page tab → Step attachments → Details for guides, with the reference). Only screen steps take
+details. A reference to a detail no accepted run has yet shows the whole screen; `kaloko docs check` warns under
+`missing_details` (the scenario does not declare it) and `no_detail` (no accepted run has it: walk and accept).
+Prefer a detail over a crop when the text names one button, field or message; keep the whole screen for orientation.
+
 Never invent a step id or a version. Use ids from the scenario files and versions from `CHANGELOG.md` or git tags.
 
 ## After a user-visible change

package/skills/kaloko/reference/evidence.md

@@ -1,12 +1,14 @@
-# Evidence for your own documentation (regulated work)
+# Quality evidence for your own documentation
 
 Use this when a team's own repository turns Kaloko runs into its documents: test protocols, reports, trace
-matrices, release summaries for a quality system. Kaloko provides the evidence and a way to check it; the team's
-own templates and skills write the documents. Kaloko never formats anything for a particular QMS, and you do not put
+matrices, release summaries for its quality management system (ISO 9001, ISO 13485, IEC 62304, ISO 27001, or GxP
+under 21 CFR Part 11 and EU GMP Annex 11, the strictest case). Kaloko provides the evidence and a way to check it;
+the team's own templates and skills write the documents. Kaloko never formats anything for a particular QMS, and you do not put
 the team's SOP structure into Kaloko.
 
 The background for people (what a record proves, the two signing paths, known gaps) is in Kaloko's help, page
-*Kaloko in regulated work (GxP)*. Evidence is a Business feature.
+*Quality evidence for your QMS* (it maps the frameworks and has a GxP section). Evidence is a Business feature.
+Kaloko provides evidence; it never makes a team compliant or certified, so never write that it does.
 
 ## The contract
 

package/skills/kaloko/reference/first-run.md

@@ -24,11 +24,17 @@ with a person who knows where to approve it.
 ## From zero to a first shared run
 
 1. `npm install --save-dev kaloko`, then
-   `npx kaloko init --agent claude --org <org>` (it prints the sample link
-   and these steps). Fill `environments` in `kaloko.config.yml` with the URL
-   the app runs on.
+   `npx kaloko init --agent claude --org <org> --project <slug> --project-name "<name>"`
+   (it prints the sample link and these steps). Ask the person how the project
+   should be called on Kaloko when you do not know; the slug is lowercase
+   (`eco-podcasty`), the name is what people see (`ECO Podcasty`). Fill
+   `environments` in `kaloko.config.yml` with the URL the app runs on. When
+   the repository holds several sites, see [Several sites in one
+   repository](#several-sites-in-one-repository) first.
 2. `npx kaloko login`: the person approves a token in the browser. Ask them
-   to; never create or paste tokens yourself.
+   to; never create or paste tokens yourself. Then `npx kaloko projects sync`
+   puts the project of the config on Kaloko with its name (a first
+   `kaloko share` would create it too).
 3. `npx kaloko doctor` and fix what it marks ✕.
 4. Draft the first scenario:
    - public pages: `npx kaloko draft <url> [url…]` writes a read-only
@@ -49,3 +55,30 @@ with a person who knows where to approve it.
 Done means: the scenario validates, the run is shared, its URL and summary
 line are in your reply (and in the issue or PR the work belongs to), and the
 person knows whether the sample or this run is what they should open.
+
+## Several sites in one repository
+
+A monorepo (`apps/*` with their own dev server), a Rails app with engines or
+several Folio sites, or routes split by host: `kaloko init` lists the sites
+it found and drafts no steps, because routes of the whole repository mix the
+sites (favicons, ad endpoints and API routes of another site end up as
+"pages").
+
+1. Ask the person which site the work is about before `init` or a walk. Do
+   not pick one yourself.
+2. Run init for that site, best against the running site so the pages come
+   from its sitemap or its navigation:
+   - `npx kaloko init --site eco-podcasty --base-url http://eco-podcasty.localhost:3000`
+   - `npx kaloko init --site apps/web` (a workspace app: its own routes and dev
+     server; `--base-url` still reads the running site when it is up)
+   Only the host of `--base-url` is asked, with short time limits; offline the
+   code is read.
+3. Read the comment at the top of `qa/flows/main-pages.yml`: it says where the
+   pages came from and which paths were skipped and why. Sharpen the steps;
+   add pages the person names.
+4. When the site is not running and has no routes of its own (a Folio site),
+   `npx kaloko init --site <name> --skeleton` writes a scenario with a TODO;
+   fill it with the pages the person names.
+
+One config can serve one site. For a second site of the same repository use
+another config (`--config kaloko.<site>.config.yml`) with its own `project:`.

package/skills/kaloko/reference/mcp.md

@@ -32,6 +32,7 @@ is null. Projects and products come complete, without pages.
 | `get_feedback` | run verdict with note, approved steps, unresolved rejections and comments, failed manual criteria (`run_id`, or `scenario` for its latest run) |
 | `list_notifications` | the token owner's inbox (`unread_only`, `limit`, `cursor`) |
 | `list_projects` | projects of the organization with counts; the slug is the `project` filter of `list_runs` and the value for `project:` in a scenario |
+| `upsert_project` | creates a project (`slug`, `name`, `visibility`, `product`; `create: true` refuses an existing one) or renames it; the same rules as `kaloko projects create\|rename\|sync` (a full token; renaming is for the project's admin). Ask before renaming |
 | `get_criteria_verdicts` | reviewer verdicts on manual or overridden criteria of a run |
 | `get_stack_items` | the pages of a stack step (`run_id`, `step`; filters `status`, `criterion`, text): path, URL, title, status and failing criteria with evidence, screenshot URLs |
 | `get_step_recording` | a step's recording and trace (`run_id`, `step`, `locale`, `viewport`, `trace: true` for the full trace): video URLs, duration, its chapter of a flow recording, failed attempts, the trace summary (failed requests, console errors, slowest request); see [recording.md](recording.md). `get_run_summary` lists trace summaries per step too |
@@ -42,7 +43,7 @@ is null. Projects and products come complete, without pages.
 | `list_products` | the products the caller reads: name, modules, the projects it maps that the caller sees, the newest release, published docs (versions, languages), who reads it (and the public link), whether the caller manages it, links to its page, changelog and docs |
 | `get_changelog` | the visual changelog of a product (`product`, `version`, `resolve: true` for the pictures, `limit`): releases newest first with the entry as written and its groups; see [docs.md](docs.md) |
 | `draft_changelog_entry` | what accepted runs since the last release (or `since`) show differently, as a Keep a Changelog draft with before/after step references (`product`, `since`) |
-| `resolve_step_image` | one step reference (`ref` = `kaloko:<scenario>/<step>?…`, `product`, `version`, `locale`, `viewport`) as a signed image URL with its run, how the version was found and canvas links; `video` (mp4, webm, duration_ms) when the step's recording plays (`media=video` / `media=image` in the ref) |
+| `resolve_step_image` | one step reference (`ref` = `kaloko:<scenario>/<step>?…[#<detail>]`, `product`, `version`, `locale`, `viewport`, `detail`) as a signed image URL with its run, how the version was found and canvas links; `video` (mp4, webm, duration_ms) when the step's recording plays (`media=video` / `media=image` in the ref); with a detail id the detail's picture and `detail` { id, name, box, size }, or the whole screen with `detail_missing` |
 | `get_docs` | a product's published docs (`product`; without `path` the versions, languages and sidebar; with `path` one page with its Markdown, sections, stale sections and, with `resolve: true`, its pictures) |
 | `docs_check` | what needs attention in the published docs of a version: broken step references, references without an accepted picture, stale sections, missing or outdated translations, release items without a picture |
 | `list_step_changes` | documentation layer: steps whose capture or status changed since the previous accepted run or `since` (`scenario`, `since`, `accepted`); see [documentation.md](documentation.md) |

package/src/cli.mjs

@@ -28,7 +28,8 @@ import { doctor, formatDoctor } from './lib/doctor.mjs'
 import { parsePlan, coverage, formatCoverage } from './lib/coverage.mjs'
 import { calibrate, formatCalibration, casesFromGolden, casesFromRun } from './lib/calibrate.mjs'
 import { pageFacts, draftScenario, scenarioYaml } from './lib/draft.mjs'
-import { detectProject, initScenario, formatDetection } from './lib/init-detect.mjs'
+import { detectProject, initScenario, skeletonScenario, scenarioHeader, formatDetection } from './lib/init-detect.mjs'
+import { checkSlug, checkName, setConfigKeys, createProject, renameProject, syncProject, shareProjectNote } from './lib/projects-cli.mjs'
 import { recheckCaptures } from './lib/recheck.mjs'
 import { resolveItems, fieldsOf, DEFAULT_LIMIT, timeLeft } from './lib/stack.mjs'
 import { DEFAULTS as JEV_DEFAULTS } from './lib/jev.mjs'
@@ -102,6 +103,14 @@ Project
                                     (qa/flows/main-pages.yml) when the project has none; asks "Keep a visual changelog?"
                                     (--docs: changelog adds CHANGELOG.md and the config block, full also docs/ folders
                                     with Diátaxis templates: tutorials, how-to, reference, explanation)
+       [--project <slug>] [--project-name "ECO Podcasty"] [--product <slug>]
+                                    Write project:, project_name: and product: into the config (also into an existing
+                                    one); signed in, the project is created or renamed on Kaloko to match
+       [--site <name|dir>] [--base-url <url>] [--skeleton]
+                                    A repository with several sites or apps: --site picks one (the others are
+                                    listed); without it no routes are guessed, and --skeleton writes a scenario with
+                                    a TODO instead. --base-url reads the pages from the running site (sitemap.xml,
+                                    then the links of its home page) instead of the code; only that host is asked
   ci github|gitlab [--scenario a.yml,b.yml] [--env preview] [--trigger deployment|pull_request] [--no-affected]
        [--out file] [--print] [--force]
                                     Write a workflow that walks what each pull request affects on its preview
@@ -250,6 +259,14 @@ Results
   comment --reply|--resolve|--reopen|--edit|--delete <id> [--note "…"] [--flow]
                                     Comment, answer and close feedback from the CLI (resolve with "Fixed in <commit>")
   projects [--json]                 Projects of the organization (use the slug as project: in a scenario or config)
+  projects create <slug> [--name "ECO Podcasty"] [--visibility open|restricted] [--product <slug>] [--json]
+                                    Create a project on Kaloko (Developer / Tester role; you become its admin);
+                                    an existing project is refused, not renamed. restricted needs Enterprise
+  projects rename <slug> --name "ECO Podcasty" [--json]
+                                    Change the name people see (the project's admin)
+  projects sync [--json]            Make Kaloko match project:, project_name: and product: of the config: create
+                                    the project when it is missing, rename it when the name differs, add it to the
+                                    product. A share never renames a project; it says when the names differ
   runs [--scenario id] [--env e] [--all] [--limit N] [--cursor c] [--json]
                                     Shared runs: the newest per scenario (with "+ N older"); --all or --scenario lists every
                                     run: --all to the last one page by page, otherwise the newest 300; --limit N lists at
@@ -1022,6 +1039,29 @@ async function affectedSelection (args, { config, root, scenario, scenarioFile }
   return affectedFor({ root, config, scenario, scenarioFile, base: typeof args.base === 'string' ? args.base : null, files: list(args.files), client, upstream: !args['no-upstream'] })
 }
 
+/** kaloko projects create|rename|sync: the service follows the command or the config (src/lib/projects-cli.mjs). */
+async function projectsWrite (sub, args) {
+  const usage = 'Usage: kaloko projects [--json]\n       kaloko projects create <slug> [--name "…"] [--visibility open|restricted] [--product <slug>] [--json]\n       kaloko projects rename <slug> --name "…" [--json]\n       kaloko projects sync [--json]'
+  if (!['create', 'rename', 'sync'].includes(sub)) throw new UsageError(`kaloko projects ${sub}: there is no such sub-command.\n${usage}`)
+  if (sub !== 'sync' && args._.length !== 2) throw new UsageError(`kaloko projects ${sub} needs one project slug.\n${usage}`)
+  if (sub === 'sync' && args._.length > 1) throw new UsageError(`kaloko projects sync takes no slug: it reads project: from the config.\n${usage}`)
+  // a project that came from a run label may keep a slug the rules of today refuse (Acme-Web): rename takes it as it is
+  const slug = sub === 'sync' ? null : sub === 'rename' && /^[^\s/?#]{1,80}$/.test(String(args._[1])) ? String(args._[1]) : checkSlug(args._[1])
+  if (sub === 'rename' && args.name === undefined) throw new UsageError(`kaloko projects rename needs --name "…": the name people see.\n${usage}`)
+  const name = args.name !== undefined ? checkName(args.name) : null
+  const { config } = await context(args)
+  if (!config.org) throw new UserError(NO_ORG)
+  const client = service(config)
+  let r
+  if (sub === 'create') r = await createProject({ client, org: config.org, slug, name: name || (slug === config.project && config.project_name ? checkName(String(config.project_name), 'project_name:') : slug), visibility: typeof args.visibility === 'string' ? args.visibility : args.visibility === true ? '' : null, product: typeof args.product === 'string' ? args.product : args.product === true ? '' : null })
+  else if (sub === 'rename') r = await renameProject({ client, org: config.org, slug, name })
+  else r = await syncProject({ client, config })
+  const { line, ...data } = r
+  if (args.json) { say(JSON.stringify(data, null, 2)); return }
+  say(line)
+  if (sub !== 'sync' && slug === config.project && name && config.project_name && name !== config.project_name) say(`Note: kaloko.config.yml still says project_name: ${config.project_name}; change it there too, or kaloko projects sync would rename the project back.`)
+}
+
 const commands = {
   async init (args) {
     const cwd = process.cwd()
@@ -1030,8 +1070,20 @@ const commands = {
     try { await access(file); exists = true } catch {}
     // a project from before the rename keeps its qawalk.config.yml (it is still read)
     try { await access(join(cwd, LEGACY_CONFIG_FILE)); exists = true; say(`${LEGACY_CONFIG_FILE} found; kept (still read; rename it to ${CONFIG_FILE} when convenient).`) } catch {}
+    // the project on Kaloko (project:, project_name:, product:): checked before anything is written
+    const projectKeys = {
+      project: args.project !== undefined ? checkSlug(args.project === true ? '' : String(args.project), '--project slug') : null,
+      project_name: args['project-name'] !== undefined ? checkName(args['project-name'], '--project-name') : null,
+      product: args.product !== undefined ? checkSlug(args.product === true ? '' : String(args.product), '--product slug') : null
+    }
+    const projectAsked = Object.values(projectKeys).some((v) => v != null)
     // what the project is (#26): framework, dev server, locales, main routes; --no-detect keeps the plain template
-    const detected = args['no-detect'] ? null : await detectProject(cwd)
+    // several sites or apps (--site picks one) and pages read from the running site (--base-url, or the dev URL)
+    let baseUrl = null
+    if (args['base-url'] !== undefined) {
+      try { baseUrl = new URL(String(args['base-url'])); if (!/^https?:$/.test(baseUrl.protocol)) throw new Error() } catch { throw new UsageError('--base-url must be the http(s) address the site runs on, e.g. http://localhost:3000.') }
+    }
+    const detected = args['no-detect'] ? null : await detectProject(cwd, { site: args.site ?? null, baseUrl: baseUrl?.href || null, probe: true })
     if (detected) say(formatDetection(detected))
     if (!exists) {
       let tpl = await readFile(join(packageRoot, 'templates', 'kaloko.config.yml'), 'utf8')
@@ -1040,13 +1092,29 @@ const commands = {
         tpl = tpl.replace(/^org: .*$/m, `org: ${args.org}`)
       }
       if (detected) {
-        const project = (detected.name || cwd.split('/').pop() || '').toLowerCase().replace(/^@[^/]+\//, '').replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '')
-        if (project) tpl = tpl.replace(/^project: .*$/m, `project: ${project}`)
+        const project = (detected.site?.name || detected.name || cwd.split('/').pop() || '').toLowerCase().replace(/^@[^/]+\//, '').replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '')
+        if (project && !projectKeys.project) tpl = tpl.replace(/^project: .*$/m, `project: ${project}`)
         tpl = tpl.replace('  local:\n    base_url:\n      default: http://localhost:3000', `  local:\n    # dev server: ${detected.command || 'start your app'}${detected.framework ? ` (${detected.framework.name}, found by kaloko init)` : ''}\n    base_url:\n      default: ${detected.url}`)
       }
+      if (projectAsked) tpl = setConfigKeys(tpl, projectKeys).replace(/^# The name people see on Kaloko.*\n# project_name: .*\n/m, projectKeys.project_name ? '' : '$&')
       await writeFile(file, tpl)
       say(`Created ${CONFIG_FILE}${detected ? ` (local: ${detected.url})` : ''}. Edit org and the staging and production environments.`)
+    } else if (projectAsked) {
+      // an existing config keeps everything else, comments included
+      const cfgFile = existsSync(file) ? file : join(cwd, LEGACY_CONFIG_FILE)
+      const before = await readFile(cfgFile, 'utf8')
+      const after = setConfigKeys(before, projectKeys)
+      if (after !== before) { await writeFile(cfgFile, after); say(`Set ${Object.entries(projectKeys).filter(([, v]) => v != null).map(([k, v]) => `${k}: ${v}`).join(', ')} in ${relative(cwd, cfgFile)}; the rest is kept.`) } else say(`${relative(cwd, cfgFile)} already says so; kept.`)
     } else if (!existsSync(join(cwd, LEGACY_CONFIG_FILE))) say(`${CONFIG_FILE} already exists; kept.`)
+    // signed in: the project on Kaloko follows the config now (created or renamed, added to the product)
+    if (projectAsked) {
+      try {
+        const { config } = await loadConfig(cwd)
+        if (!config.org || config.org === 'my-org') say('The project goes to Kaloko once org: names your organization (kaloko init --org <slug>, or kaloko login): then kaloko projects sync.')
+        else if (!process.env[config.share?.token_env || 'KALOKO_TOKEN']) say('Not signed in, so the project is only in the config: kaloko login, then kaloko projects sync (a first kaloko share also creates it with this name).')
+        else say((await syncProject({ client: service(config), config })).line)
+      } catch (e) { say(`! The project is in the config but not on Kaloko yet: ${String(e.message).split('\n')[0]} kaloko projects sync tries again.`) }
+    }
     // the visual changelog (docs/DOCS-CHANGELOG.md): asked once; --docs=off|changelog|full for scripts and agents
     let docsMode = typeof args.docs === 'string' ? args.docs : null
     if (docsMode && !['off', 'changelog', 'full'].includes(docsMode)) throw new UsageError('--docs must be off, changelog or full.')
@@ -1115,16 +1183,21 @@ const commands = {
     if (detected && !args['no-scenario']) {
       try {
         const { config, root } = await loadConfig(cwd)
-        if (!(await scenarioFiles(config, root)).length) {
-          const scenario = initScenario(detected)
+        const skeleton = !!args.skeleton
+        if ((await scenarioFiles(config, root)).length) {
+          // there are scenarios already
+        } else if ((detected.ambiguous || detected.needsUrl) && !skeleton) {
+          say(`No scenario drafted: ${detected.ambiguous ? 'say which site with --site' : `add --base-url for ${detected.site.name}`}, or write the steps yourself (--skeleton gives a file with a TODO to start from).`)
+        } else {
+          const scenario = skeleton ? skeletonScenario(detected) : initScenario(detected, { project: detected.site?.name || null })
           const problems = validateScenario(JSON.parse(JSON.stringify(scenario)))
           if (problems.length) throw new Error(problems.join('; '))
           first = join(cwd, 'qa', 'flows', 'main-pages.yml')
           await mkdir(join(cwd, 'qa', 'flows', 'steps'), { recursive: true })
-          await writeFile(first, `# First scenario drafted by kaloko init from ${detected.routes.length ? 'the route files' : 'the home page'}; sharpen purposes and criteria, add the flows that matter.\n${scenarioYaml(scenario)}`)
+          await writeFile(first, `${scenarioHeader(detected, { skeleton })}${scenarioYaml(scenario)}`)
           const open = join(cwd, 'qa', 'flows', 'steps', 'open.mjs')
           if (!existsSync(open)) await writeFile(open, "// Opens the step's page (kaloko init).\nexport default async ({ page, url }) => { await page.goto(url(), { waitUntil: 'domcontentloaded' }) }\n")
-          say(`Drafted ${relative(cwd, first)}: ${scenario.nodes.length} page(s) in ${scenario.locales.join(', ')}`)
+          say(skeleton ? `Drafted ${relative(cwd, first)}: a skeleton with a TODO; add the pages that matter.` : `Drafted ${relative(cwd, first)}: ${scenario.nodes.length} page(s) in ${scenario.locales.join(', ')}${detected.skipped?.length ? `; ${detected.skipped.length} path(s) that are not pages left out (listed at the top of the file)` : ''}`)
         }
       } catch (e) { say(`No scenario drafted: ${e.message.split('\n')[0]}`) }
     }
@@ -1928,6 +2001,8 @@ const commands = {
       return
     }
     let manifest = await buildManifest({ run, scenario, config, root, catalog: [] })
+    // a project the share creates gets the name of the config (project_name:), also for runs started before it was set
+    if (manifest.project?.slug && manifest.project.slug === config.project && config.project_name) manifest.project.name = String(config.project_name).replace(/\s+/g, ' ').trim()
     await writePreview({ run, manifest })
     // the plan and storage before anything is sent; recordings travel on plans with the recordings feature only
     const u = await client.request('GET', `/orgs/${config.org}/usage`).catch(() => null)
@@ -1945,6 +2020,8 @@ const commands = {
         files.add(n.stack.items)
         const idx = await readJson(join(run.dir, n.stack.items), { items: [] })
         for (const it of idx.items) for (const byVp of Object.values(it.captures || {})) for (const c of Object.values(byVp)) [c.png, c.thumb, c.html, c.eval].filter(Boolean).forEach((p) => files.add(p))
+        // a page's own attachments (the focus shots of the keyboard walk on the first pages)
+        for (const it of idx.items) for (const a of it.attachments || []) files.add(a.file)
       }
     }
     // personal data (#64): nothing goes up with an unmasked e-mail, phone number, birth number or IBAN in it
@@ -2003,6 +2080,9 @@ const commands = {
     meta.shared = { url: fin.url, at: new Date().toISOString(), expires_days: created.expires_days }
     await writeFile(join(run.dir, 'meta.json'), JSON.stringify(meta, null, 2) + '\n')
     say(`Shared ${manifest.id} (${files.size} files, expires in ${created.expires_days} days)\n${fin.url}`)
+    // the project as Kaloko has it: created now with project_name:, or named differently (a share never renames)
+    const projectNote = shareProjectNote(created.project, config)
+    if (projectNote) say(projectNote)
     // what waits for a person, with the review-mode link to give them (approvals of unchanged steps carry over)
     const review = shareReviewLine(fin.review)
     if (review) say(review)
@@ -2015,7 +2095,7 @@ const commands = {
       say(r.ok ? `PR comment ${r.action}: ${r.url}` : `PR comment skipped: ${r.reason}.`)
     }
     // --json: what a script needs next, the run id and its canvas URL (the lines above went to stderr)
-    if (args.json) say(JSON.stringify({ run: manifest.id, url: fin.url, scenario: scenario.id, files: files.size, expires_days: created.expires_days, review: fin.review || null, ...(args.pr ? { pr_comment: prComment } : {}) }, null, 2))
+    if (args.json) say(JSON.stringify({ run: manifest.id, url: fin.url, scenario: scenario.id, files: files.size, expires_days: created.expires_days, review: fin.review || null, ...(created.project ? { project: created.project } : {}), ...(args.pr ? { pr_comment: prComment } : {}) }, null, 2))
   },
 
   async sync (args) {
@@ -2359,11 +2439,15 @@ const commands = {
   },
 
   async projects (args) {
+    const sub = args._[0]
+    if (sub !== undefined && sub !== 'list') return projectsWrite(sub, args)
     const { config } = await context(args)
     const data = await service(config).request('GET', `/orgs/${config.org}/projects`)
     if (args.json) { say(JSON.stringify(data, null, 2)); return }
-    if (!data.length) { say('No projects yet. Create one in Settings → Projects or with POST /api/v1/orgs/<org>/projects.'); return }
+    if (!data.length) { say('No projects yet. kaloko projects create <slug> --name "…" creates one (or Settings → Projects in the app).'); return }
     for (const p of data) say(`${p.slug.padEnd(24)} ${p.name}${p.adhoc ? ' (from runs only)' : ''}  ${p.scenarios} scenario(s), ${p.runs} run(s)${config.project === p.slug ? '  ← this config' : ''}`)
+    const mine = data.find((p) => p.slug === config.project)
+    if (mine && config.project_name && mine.name !== config.project_name) say(`Note: ${mine.slug} is named "${mine.name}" here and "${config.project_name}" in the config; kaloko projects sync renames it.`)
   },
 
   async compare (args) {
@@ -2571,11 +2655,18 @@ const commands = {
       return
     }
     // check: the scenario files say which steps exist
-    const scenarios = new Map()
-    for (const f of await scenarioFiles(config, root).catch(() => [])) { try { const s = yaml.load(await readFile(f, 'utf8')) || {}; if (s.id) scenarios.set(String(s.id), new Set((s.nodes || []).map((n) => String(n.id)))) } catch {} }
+    const scenarios = new Map(); const details = new Map()
+    for (const f of await scenarioFiles(config, root).catch(() => [])) {
+      try {
+        const s = yaml.load(await readFile(f, 'utf8')) || {}
+        if (!s.id) continue
+        scenarios.set(String(s.id), new Set((s.nodes || []).map((n) => String(n.id))))
+        for (const n of s.nodes || []) details.set(`${s.id}/${n.id}`, new Set((n.details || []).map((d) => String(d?.id))))
+      } catch {}
+    }
     let client = null
     if (!args.offline) { try { client = service(config) } catch {} }
-    const r = await docs.docsCheck({ root, config, product, client, scenarios: scenarios.size ? scenarios : null, version })
+    const r = await docs.docsCheck({ root, config, product, client, scenarios: scenarios.size ? scenarios : null, details: scenarios.size ? details : null, version })
     say(args.json ? JSON.stringify(r, null, 2) : docs.formatCheck(r))
     if (!r.ok || (args.strict && r.warnings)) process.exitCode = 1
   },

package/src/lib/build.mjs

@@ -37,9 +37,8 @@ export async function buildManifest ({ run, scenario, config, root, catalog = []
       if (spec) await writeJson(join(run.dir, spec), cap.spec)
       caps.push({ locale: c.locale, viewport: c.viewport, cap, ev, files: { png: cap.files.png, thumb: cap.files.thumb || null, html: cap.files.html || null, tree: cap.files.tree || null, eval: `steps/${c.node}/${c.locale}/${c.viewport}.eval.json`, spec }, ...(cap.live ? { live: cap.live } : {}) })
     }
-    // focus screenshots of the keyboard walk (#19): only those of the current captures, not of earlier walks
-    const shots = new Set(caps.flatMap((c) => (c.cap.keyboard?.shots || []).map((s) => s.file)))
-    const out = assembleNode({ node, pos: pos.get(node.id), locales, viewportNames: node.kind === 'email' ? mailKeys : viewportNames, captures: caps, attachments: attachments.filter((a) => a.node === node.id && (a.kind !== 'focus' || shots.has(a.file))) })
+    // focus shots and details count only when a current capture names them (manifest-core.mjs stepAttachments)
+    const out = assembleNode({ node, pos: pos.get(node.id), locales, viewportNames: node.kind === 'email' ? mailKeys : viewportNames, captures: caps, attachments })
     await attachMedia(out, { run, entries: media, captures: caps })
     nodes.push(out)
   }