@zaip-ai/cli 6.3.0 → 7.5.0

package/templates/.agents/design/design-system-maker/API.md

@@ -0,0 +1,468 @@
+# Maker collection API V1 — measured evidence extension
+
+## Chat source workflows
+
+The installed `runtime/chat-cli.mjs --workspace PATH --request RELATIVE.json` supports
+authenticated `discover`, `list`, `show`, `job`, `generate-url`, `reprocess-source`,
+`repository`, `import-design`, `rebuild-document` and `compose`. It verifies the current
+installation manifest, launcher lease and authenticated probe before using the existing
+Origin/nonce/revision-guarded API. A stale build/protocol fails; there is no alternate
+direct-service path after a host/API denial. No source instructions or scripts execute.
+
+`POST /api/local-sources` accepts repository/import-design/rebuild-document/compose
+requests with a stable `operation_id`, destination identity/revision and their bounded
+source-specific fields. Local outputs use `source.type:repository|design-markdown|composition`,
+`url:null`, relative locators, file SHA256/byte inventory or exact source revision/DESIGN
+artifact hashes. Existing URL entries/proposals remain readable. The local handoff uses
+schema2 `maker-local-source-v1`; it is not the old URL adapter shape. Local references
+remain partial; frontend shows the locator and directs URL recollection separately.
+
+Document rebuild parses the immutable hash-verified DESIGN.md and preserves old revisions.
+Composition parses those same pinned Markdown bytes, requires two to eight sources and
+explicit per-facet priorities, records conflicting alternatives and creates a new identity.
+Source hashes come from artifact inventory, not the dynamic detail.designMd projection.
+Stable operation replay returns its existing job/result; mismatched reuse conflicts, and
+timeout does not trigger an automatic second operation. Read job/entry to resolve it.
+For exact requests, supported subsets and bounds, use the distributed
+[Maker skill](../../skills/zaip-skill-design-maker/SKILL.md) and its four workflow references.
+
+The catalog's **Avançado** link opens `/advanced/`, a Portuguese guide with current-origin
+PowerShell examples, code-based lookup, agent instructions, endpoint reference and
+optional mutation guidance. Copy actions do not execute requests. The guide never embeds
+the session nonce; mutation examples obtain it when the user runs them.
+
+## Stable short design codes
+
+List summaries and details expose `design_code` ("001", "002", ...; grows past 999).
+The collection assigns existing entries oldest-first on first use and reserves new
+numbers monotonically under its writer lock. Codes are persisted in the sealed,
+atomically written `data/design-codes.json` registry. Reprocess, sort, pagination,
+trash/restore and restart preserve the code. Numbers are never recycled. Preserve
+this registry with collection backups; codes are local to this collection, not global.
+Immutable revision records and their UUIDs remain unchanged.
+
+To use "design 003" in an agent, find `design_code: "003"` in `GET /api/extracts`
+(follow pagination), then request `GET /api/extracts/:id` using that item's full ID.
+For an exact historic snapshot also specify its revision. Catalog and viewer search
+match short codes with or without `#`; cards and details display `#001`, `#002`, etc.
+above the design identity. The API field contains the numeric string without `#`.
+
+## Captured theme projection
+
+List/detail recompute the visual demonstration from verified saved proposals. Browser
+computed observations take precedence over static declarations for the captured body
+colors and typography. Primary requires sampled action background paint; accent is
+inferred independently from distinct colored paint or gradient stops. Ordinary heading,
+body and FAQ text remains candidate evidence without becoming an action/highlight role;
+a low contrast color remains a candidate. Semantic role assignment retains observation IDs and viewport.
+Missing roles use neutral local
+fallbacks, never a Maker brand accent. Historical report bytes, scores and revisions
+remain unchanged; no network extraction is required to refresh their presentation.
+`visual_model.color_candidates` adds up to 32 safe scalar colors with `source:"observed"|"declared"`,
+`kind:"inferred"`, original property, evidence IDs, provenance, role hint and rationale.
+Observed candidates can also retain an element ID and whether the element intersects
+the captured viewport. A sampled footer outside that viewport is computed-style evidence,
+not screenshot proof. Gradient stops are scalar proposals; source gradients/CSS are never
+applied to the local preview. SVG paint and pseudo-element evidence retain their selectors.
+Declared candidates can belong to inactive themes and do not fill missing captured roles.
+The details palette and catalog distinguish candidate origins; the full diagnostic preserves
+all retained declared CSS colors, including other states/themes. The diagnostic shell stays white.
+Button radii apply to controls, not large content panels; unsupported component styles
+and unobserved shadows are not borrowed from unrelated CSS declarations.
+
+`visual_model.coverage` records `sampled|incomplete|legacy-unknown`, bounded inspection/sample/
+omission counts, method, readiness and limitations. `sampled` means a bounded sample with
+the recorded readiness checks satisfied, never complete site coverage. New capture inspects
+at most 2000 distributed DOM nodes and retains at most 48 element/pseudo samples within the
+existing 400 browser-observation budget, balancing actions, headings/ancestors, regions,
+surfaces and SVG paint. Repeated identical controls do not consume every category quota.
+After initial DOM/stylesheet readiness, collection waits up to six additional seconds for
+complete DOM, loaded fonts, non-lazy images and repeated layout geometry. Pending/failed
+images, unavailable fonts, unstable layout and inspection omissions remain explicit gaps.
+CSS background-image readiness, future resources, interactions and other viewports are not
+established. Historical captures without readiness metadata remain `legacy-unknown`;
+static-only collections retain `incomplete` coverage. Generated DESIGN.md and REPORT.md
+include candidate provenance and coverage; immutable historic exports stay unchanged.
+When the model exceeds 64 KiB, component detail, scales and repeated provenance contexts
+are omitted before representative distinct observed/declared colors; any omissions are
+reported and full observations remain in the proposal.
+
+## Explicit browser collection and local favicon
+
+Generate and reprocess accept optional `mode:"http"|"browser"`. Generate defaults to
+HTTP; reprocess without a mode preserves browser collection when a browser job or
+runtime-rendered capture exists in the latest 100 revisions, including after an
+intervening failed/HTTP revision. Otherwise it uses HTTP. An explicit mode overrides
+this recovery. The web form selects browser mode by default when available.
+HTTP capture is bounded at 4 MiB/response, 8 MiB total,
+10 seconds/request, 30 seconds total and 32 resources. Proposal and job validators
+share these constants. DOM sampling retains 500 nodes and reports omissions instead
+of rejecting an otherwise readable large page.
+`GET /api/session` reports `capabilities.browser` with availability, reason,
+`method:"local-isolated-cdp"` and `human_wait_ms:120000`. Browser mode uses a temporary
+owned profile and a bounded public-network proxy; it does not reuse personal cookies,
+install dependencies or automatically solve access challenges. Its additional phases
+are `browser-open`, `browser-wait` and `browser-capture`. Collected DOM/CSS is passed
+in memory to extraction rather than fetched again with the HTTP reader.
+Media downloads and browser background tasks are limited independently of access
+checks. Proxy destinations must first be observed in the page's intercepted requests;
+unrelated browser component/model downloads are denied before an outbound connection.
+Browser jobs may retain bounded `browser.traffic` counters by public host
+and resource type, with proxy wire bytes separate from page bytes. No request paths,
+queries, cookies or headers are retained in those counters. Omitted media is recorded
+as a capture limitation; the wire budget is 32 MiB and the wait remains 120 seconds.
+
+`POST /api/jobs/:id/cancel` accepts `{expected_revision}` using the accepted entry
+revision. Normal Origin/nonce guards and revision checks apply. Cancellation is a
+terminal failed job with `failure.kind:"cancelled"`; it affects only that owned job.
+The Viewer reprocess action starts the saved URL/mode immediately and opens the
+job dialog for monitoring. It does not add a confirmation step or URL/mode editor;
+polling retry refreshes that job without submitting another extraction.
+
+`summary.visual.faviconUrl` names `GET /api/extracts/:id/favicon?revision=N` when a
+verified local icon exists. The collector preserves bounded, validated raster/ICO
+bytes and their inventory hash inside the immutable revision. No source SVG/HTML is
+served as an icon. Missing icons retain the initials fallback; viewing an older
+revision does not fetch or mutate it. Reprocess explicitly to obtain a new icon.
+
+The diagnostic page preserves the original white layout independently of the
+extracted theme. Its score tiles use the derived `design_score` heuristic described below,
+with individually calculated grades rather than copied reference scores. Demonstration components use bounded
+normalized tokens; unavailable source sections are identified explicitly.
+
+### Design Score projection
+
+List summaries and detail responses add `design_score`, derived from the verified saved
+proposal/report and selected visual model. Method `design-score-v3` evaluates seven
+reference categories: Color Discipline, Typography, Spacing System, Border Radii,
+Tokenização da origem, Lint Compliance and Accessibility. Each includes grade, score, observed
+value, ideal target, explanation and evidence IDs. The overall is the rounded equal-weight
+mean of evaluated category scores: A ≥90, B ≥80, C ≥70, D ≥60, F <60.
+
+Original count-based rules are adapted from the reference `lib/design-md.cjs`;
+unreachable excess-spacing/radius branches are fixed. Tokenization now measures actual
+visual declarations containing `var()` because the original confidence ledger is absent.
+Contrast uses available opaque semantic foreground/background pairs, with a detailed
+ratio table. It is not a full accessibility audit. Lint now runs locally on the extracted
+visual model (`visual-token-lint-v1`): supported token values, evidence links, provenance,
+required semantic colors, body font and spacing/radius scales. Each error deducts 20
+points and each warning 5 from 100, floored at 0. The `lint` object exposes the rules,
+token count, error/warning counts and findings (first 100, with omitted count).
+Its measured score participates in the final equal-weight average. With no model tokens
+lint remains unavailable and is excluded. This is not the remote site's code lint or
+the Google DESIGN.md linter. Sampling and bounded inventories are disclosed.
+
+The UI uses this projection for catalog, viewer and white diagnostic. Existing
+`score`, `score_kind`, `quality` and immutable report exports retain extraction-coverage
+semantics for compatibility. The new score does not rewrite old revisions, fetch remote
+pages or certify visual quality; its versioned method differs from the original score.
+
+## Unified per-reference visual model and failed collection
+
+`summary.visual_model` and `detail.visual_model` use the same additive contract:
+`{schema_version:1,method:"declared-semantic-v1",status:"inferred"|"unavailable",
+tokens,components,theme,variants,unknown,limitations}`. New report exports also retain
+that model. Existing saved proposals/reports derive it in their read projection;
+historical artifact bytes, scores and receipts are never rewritten or fetched again.
+Revisions without proposal/report remain explicitly unavailable.
+
+Tokens have `{value,property,kind:"inferred",evidence,provenance,reason}` or null.
+`tokens.colors` roles are background, foreground, primary, primary_foreground,
+secondary, muted, accent, border, card, card_foreground. Typography has string
+body_family/heading_family and scalar size/weight/line_height/letter_spacing tokens.
+Spacing/radii/shadows/borders are bounded arrays of the same token rows. Components
+retain static tag/selector/role/evidence descriptors plus optional local tokens for
+background, foreground, border, radius, padding, font_family, font_size, font_weight,
+shadow. Only simple exact tag/selector matches are represented, never computed cascade.
+Theme active is unknown; variants identify declared selectors. Missing tokens require
+an explicitly labeled local demonstration fallback. Extracted URLs, HTML, CSS rules,
+scripts and font-face assets are never applied or executed on the app origin.
+
+Entry/job/summary/detail may retain `failure:{kind,http_status:number|null,source_url,
+observed_at,stage,retry:"explicit",message}`. Source URL is redacted; no response body,
+cookies, headers or challenge query is exported. HTTP403 challenge is access-challenge;
+other non200 is http-error. Other failures are bounded extraction-error. New failure
+metadata survives immutable revision receipts/restart. Historical failed entries retain
+their original error with unknown structured detail. Their report.status is failed,
+not legacy-unavailable. Collecting status is separate. A valid public URL blocked by
+the collector is not an old revision: show the cause and explicit retry/edit URL/open
+browser assistance, without bypassing an access challenge or substituting another host.
+Preview/diagnostic pages are managed frontend routes bound to local ID/revision, with
+native demo components; they never render external source HTML. Coverage score89 is
+extraction evidence, not a visual-quality/archetype/accessibility grade.
+
+## Runtime contract for collection and report clients
+
+This additive contract preserves existing V1 revisions. A completed collection job
+may produce a **partial static report**: job completion does not imply browser
+rendering, authentication, visual quality, accessibility certification or central
+token promotion. Old revisions without report artifacts expose
+`report.status: "legacy-unavailable"`; they are never silently rescored or rewritten.
+
+```json
+{
+  "report": {
+    "schema_version": 1,
+    "method_version": "css-evidence-v1",
+    "status": "measured-evidence",
+    "score": 0,
+    "score_kind": "extraction-evidence-coverage",
+    "metrics": [],
+    "sampling": {"total": 0, "sampled": 0, "truncated": 0},
+    "colors": [], "typography": [], "spacing": [], "radii": [],
+    "components": [], "resources": [], "gaps": []
+  },
+  "job": {
+    "status": "running", "phase": "fetch-html",
+    "started_at": null, "completed_at": null, "duration_ms": null,
+    "progress": {"percent": null, "resources_received": 0},
+    "events": []
+  }
+}
+```
+
+The JSON illustrates shape only, not a measured result. Report score is the sum of
+four ratios times fixed weights: category coverage35, retained declaration
+sampling25, normalized color resolution20 and declared token reuse20. Every metric
+stores numerator, denominator, ratio, weight and explanation. Zero denominators
+produce ratio0 with an explicit gap. This is an extraction evidence score, never
+a rendered design/LLM/AA score. Values carry observation IDs and source provenance;
+RGB/HSL/hex and bounded custom-property resolution remain inferred from declarations.
+Browser-computed evidence can establish sampled values at the captured viewport;
+it does not establish the full cascade, every state or a global active theme.
+These four coverage ratios belong to the retained report contract. The current
+seven-category `design_score` projection and `generated_token_quality` above are
+separate assessments and do not rewrite historical report scores.
+
+CSS declarations remain globally bounded at2048. Sampling prioritizes root/theme
+variables, font descriptors, component/design declarations, then other properties.
+Each stylesheet records total/sample/truncated counts; exceeding the retained sample
+does not discard the stylesheet. Existing resource, time, byte, DNS/IP pinning,
+redirect and CPU bounds remain in effect. The richer evidence inventory is capped at
+2949 observations (500 markup, 2048 CSS, 400 browser/optional host styles, 1 unknown capability)
+and2048 token candidates. Each text artifact remains bounded at4MiB, screenshot at8MiB;
+payload preflight rejects before output persistence and import uses the same byte caps.
+
+| Additional route | Contract |
+| --- | --- |
+| GET `/api/extracts/:id/report?revision=2` | Hash-verified `report.json`, or404 for legacy revisions. Detail includes `report` and `quality.status:"measured-evidence"` when retained. |
+| GET `/api/extracts/:id/report-markdown?revision=2` | Hash-verified `REPORT.md` as plain text. |
+| POST `/api/extracts/:id/reprocess` | `{expected_revision,url?,mode?}`. Uses the saved exact safe request URL, stable ID and existing name; omitted mode preserves recent browser collection. Legacy/unsafe unavailable URLs require an explicitly supplied safe URL; sanitized display URLs are never reconstructed silently. |
+| DELETE `/api/extracts/:id` | `{expected_revision,expected_trash_revision}`. Recoverable project-owned trash receipt, retaining every revision and artifact. Collecting/conflicting revisions are rejected. |
+| GET `/api/trash` | Paginated trashed summaries with `trash_revision` and timestamp. |
+| POST `/api/trash/:id/restore` | Same two revision guards; restores the retained reference, never re-extracts or overwrites its artifacts. |
+
+All mutations require the existing exact Host/Origin, per-process nonce and bounded
+JSON body. Trash is a receipt-backed metadata operation, not physical file deletion.
+Its receipt and marker use verified atomic writes under the collection writer lock;
+interrupted receipt/marker acknowledgement is recoverable. It is not a whole-filesystem
+transaction or protection against another party authorized to rewrite project files.
+
+`request_url` retains only a policy-approved exact target, including safe version
+queries, separately from the final redirect URL and redacted display provenance.
+Secret-bearing URLs are rejected or explicitly unavailable for replay. Job phases,
+event timestamps, resource counters and durations come from actual work. Percent is
+always null; clients show progress immediately after submission and poll real events.
+
+### Concrete additive response fields
+
+Summary adds `request_url:string|null`, `replay_available:boolean`,
+`replay_unavailable_reason:string|null`, `trash_revision:integer` (initially0),
+`deleted_at:ISO|null`, `score:number|null`, `score_kind:string|null` and
+`sampling:{total,sampled,truncated}|null`. Safe version queries remain in request_url;
+`url` is the redacted final display URL. `provenance.request_url` and
+`provenance.final_url` distinguish the requested target from the redirect result.
+
+Detail adds the full `report` and `quality:{grade:null,overall:number|null,status,
+score_kind,metrics,reason}`. `report.colors` retains declared CSS colors; additive
+`visual_model.color_candidates` keeps rendered candidates and their distinct provenance.
+The maximum12 `visual.inferred_swatches` are only a preview. Category rows have
+`{value,declared_value,property,kind,method,occurrences,evidence:string[],provenance}`.
+Provenance contains source URL/hash/selector/method and capability origin. Typography
+rows keep property names: font-family, font-size, font-weight and shorthand font are
+distinct declarations. Resources retain `{kind,url,bytes,hash}` and received-source
+metadata. `report.element_count` counts HTML elements, including metadata; it is not a
+component count. `report.components` groups static UI candidates with
+`{tag,selector,role,text,occurrences,kind,evidence,provenance}`. No candidate is a
+verified reusable component. `tokens.elements` preserves the separate DOM inventory.
+
+Jobs add `phase`, `started_at:ISO|null`, `completed_at:ISO|null`,
+`duration_ms:integer|null`, `progress:{percent:null,resources_received:integer}` and
+`events:[{at:ISO,phase,resources_received}]` (maximum64). Phases are queued,
+fetch-html, parse-css, fetch-css, browser-open, browser-wait, browser-capture,
+build-report, verify-artifacts, commit,
+completed and failed. `entry_status` and `render_available` describe evidence
+separately from job completion. Logs are bounded real event descriptions; no
+simulated percentages. Display completed as “Relatório gerado” and sample limits as
+“CSS amostrado”, retaining counts and static/browser limitations.
+
+Trash mutations return the verified metadata receipt
+`{schema_version,workspace_hash,id,entry_revision,entry_hash,trash_revision,state,
+observed_at,previous_checksum}`. Initial active state has trash_revision0; each
+successful trash or restore increments it once without changing entry revision.
+GET trash returns the same paginated envelope as GET extracts. Conflicts return409;
+missing/wrong nonce or foreign Origin returns403. Restore never fetches the source.
+
+
+The builtin-only runtime is installed under `runtime/` and imports the installed
+portable `.agents/tools/visual-url/` extractor by relative path. No sibling repository,
+maintainer package/node_modules, implicit LLM/provider/npx/post-hook or browser install
+is required. Source reference declarations and hashes are in SOURCE-PROVENANCE.json;
+NOTICE preserves observed local attribution without asserting upstream license clearance.
+
+Start this bounded server explicitly:
+
+```powershell
+node .agents/design/design-system-maker/runtime/serve.mjs --workspace .
+```
+
+It binds a dynamic port on 127.0.0.1 and prints observed app/workspace/PID/origin identity.
+Kernel-held exclusion keyed by the real data directory prevents a second writer.
+Windows uses a named pipe; other platforms use a bounded loopback-only exclusion
+listener selected before acquisition. Acquisition failure never changes authority.
+The standalone server is useful for explicit development; the installed EXE starts
+the verified launcher runtime, serializes startup and reuses an authenticated lease.
+See [README.md](README.md) for Node discovery, hidden launch, browser readiness and
+the authenticated stop command. Never kill a process merely because it uses a port.
+
+## Request boundary
+
+All requests require the exact local Host; supplied Origin must match exactly and
+cross-site Fetch Metadata is rejected. No CORS is enabled. GET `/api/session` returns
+`{app,schema_version,data_schema_version,workspace_hash,runtime_identity,pid,origin,nonce,capabilities}`.
+Frontend code keeps that nonce only in session memory. Every POST and DELETE sends:
+
+```javascript
+const session = await fetch('/api/session').then(r => r.json());
+const response = await fetch('/api/generate', {
+  method: 'POST',
+  headers: {'Content-Type': 'application/json', 'X-Maker-Nonce': session.nonce},
+  body: JSON.stringify({url: suppliedUrl, name: suppliedName})
+});
+```
+
+The browser sends its same-origin Origin automatically. A nonbrowser authorized client
+must send that exact Origin explicitly. Nonce is per-process and never stored in data or
+logs. Body is JSON, maximum 64 KiB and 2-second read deadline. Generate whitelist is exactly
+`url`, optional `name`, optional stable `id`, optional `expected_revision`, optional `mode`. No provider,
+legacy noReuse/localBrowserProxy/noLlmRetry, shell hook, output path, capture path,
+fixture_authorization or limit override is accepted from a page. Invalid requests create
+no job/entry. The private-fixture/capture policy belongs only to explicit host configuration.
+
+Optional `--host-config .local/maker-host.json` supplies a bounded project-owned JSON
+with `fixture_origins` (maximum16 exact loopback origin/reference entries) and/or
+`captures` (maximum16 URL-keyed normalized capture configurations). Never infer this
+authorization from a public request. Ordinary remote extraction retains Task4's pinned
+DNS/connection/redirect guards. The runtime supports2 active extraction jobs and5 total
+accepted jobs including queued work; a full queue returns429 before creating orphan data.
+
+## Endpoints and compatibility
+
+| Endpoint | Contract |
+| --- | --- |
+| GET `/.zaip-maker/health` | App/workspace/runtime/PID identity and observed origin;2 active /5 accepted capacity. |
+| POST `/.zaip-maker/control` | Launcher-only authenticated probe/stop, separate private control secret, exact Host, zero body and no browser Origin/Fetch Metadata. Never available through the browser nonce. |
+| GET `/api/extracts?offset=0&limit=100` | `{schema_version:1,extracts:summary[],total,offset,limit,next_offset}`; limit1–100, full collection by paging. |
+| GET `/api/extracts/:id` | `{summary,tokens,quality,designMd,...entry,proposal,revisions,revision_count,history_offset,history_limit,preview_html:null}`. |
+| GET `/api/extracts/:id?revision=2&history_offset=0&history_limit=20` | Immutable prior revision; history page defaults20, maximum100, newest range first. |
+| GET `/api/extracts/:id/design?revision=2` | Verified Markdown served as `text/plain`, never active HTML. |
+| GET `/api/extracts/:id/proposal?revision=2` | Verified normalized JSON evidence. |
+| GET `/api/extracts/:id/screenshot?revision=2` | Actual retained PNG only, hash-verified on read;404 if unavailable. |
+| POST `/api/generate` | 202 `{id,jobId,url,status:'queued',log,job,entry:summary}`. New ID generated when omitted. Re-extraction needs current `expected_revision`; ID slug stays stable. |
+| GET `/api/jobs/:id` | `{id,entry_id,status,created_at,updated_at,result_revision,error,url,summary,log}`. Status queued/running/completed/failed; no provider stdout. |
+
+Summary preserves the reference API's fields: slug, name, host, url, theme, archetype,
+grade, score, previewVariant, designMdPath, designMdUrl, previewUrl, rawPreviewUrl, visual.
+It adds stable id/status/revision/time/provenance/capabilities/uncertainty. Unobserved theme,
+archetype and visual-quality grades remain null. Extraction coverage is measured only
+when verified report artifacts exist. `visual.inferred_swatches`
+contains at most12 normalized color candidates with kind/evidence/method; label them CSS
+declarations/inferred candidates. Actual screenshot URL appears only when bytes exist.
+`tokens.components` contains static UI candidates; `tokens.candidates` remains inferred,
+never central tokens. `quality.overall` remains null for revisions without a measured
+report; otherwise it retains extraction coverage, separately from `design_score`.
+Collection statuses are
+collecting/partial/ready/failed; ready evidence never proves faithful rendered implementation.
+
+Legacy `previewUrl`, `rawPreviewUrl` and `preview_html` remain null; managed
+`/viewer/preview.html?id=...&revision=N` and `/viewer/diagnostic.html?id=...&revision=N`
+render native demonstrations and diagnostics from the verified selected revision.
+Old outputs/preview.html routes are absent. External HTML, source scripts and arbitrary filesystem files are never
+served at app origin. Render captured text/Markdown/JSON with textContent or equivalent
+escaped text. Verified screenshot PNG and bounded favicon raster/ICO are the external visual artifacts served, with nosniff and restrictive
+CSP. External active content would require a separate isolated origin/sandbox contract;
+the native demonstration pages do not grant that capability. The static server serves only managed frontend assets at catalog,
+viewer, generate, shared/styles/assets routes, with `frame-src 'none'`. UI specialization
+must respect this contract rather than inserting source HTML or inline executable scripts.
+
+## Data ownership and recovery
+
+Project-owned storage is `.agents/design/design-system-maker/data/`, separate from managed
+runtime/frontend/build/exe. The server seeds absent metadata once; no maintainer dataset is
+committed or distributed. Its `.gitignore` is seeded only if absent and custom content is
+preserved. `collection.json` binds schema1 and a hash of the real workspace path; another
+workspace/future schema fails closed without migration. A backup/restore contract is
+required for a separately authorized move/migration; no query silently migrates data.
+
+`entries/<id>/revisions/r-000001/` holds immutable entry.json, receipt.json and, when
+complete, proposal.json/handoff.json/DESIGN.md, measured report.json/REPORT.md when present,
+and optional screenshot.png. Collecting or failed
+revisions have no fake extraction artifacts. `entries/<id>/state.json` points to the latest
+verified metadata; jobs live in `jobs/<id>.json`. Every new attempt increments revision and
+retains earlier successes, uncertainty and exports. Revision receipts bind workspace,
+entry hash and artifact inventory. Import reads the extractor's actual persisted
+receipt.json and every referenced byte/hash, validates proposal/handoff/design relationships,
+then commits that verified inventory. A runtime result object alone is insufficient.
+
+Writes stage files and use per-file atomic replacement, a sealed journal and roll-forward
+before state/index acknowledgement. No whole-filesystem transaction or power-loss durability
+is promised. Complete journal recovery verifies all stages before writing; pre-journal
+orphans remain unacknowledged recovery material. Known temporary stage files remain retained,
+never counted as jobs. Crash after a partial/ready revision but before job completion
+reconciles the job from its already committed revision receipt without repeating network.
+Other collecting/interrupted jobs become failed with an explicit interrupted reason and
+preserved history; retry is explicit, never automatic provider activity.
+
+`index.json` is disposable. Startup rebuilds it from verified revision metadata and keeps
+an in-memory metadata index; polls do not rehash every PNG or scan the full history. List
+and revision history are paginated. Requested artifacts are hash-verified when read; full
+artifact verification also occurs on import/commit. Corrupt future metadata, receipts,
+symlinks/reparse points, path traversal or altered artifacts fail closed. Checksums provide
+consistency, not authenticity against a party already authorized to edit the workspace.
+
+Runtime-only fixtures and API checks prove these boundaries and persistence. Rendered UI,
+independent screenshot examination, central catalog specimens and an EXE require their
+own actual served/rendered/executable proof; do not infer them from API or source checks.
+The catalog must expose every list page via load-more/pagination rather than hide items
+after100. History must similarly expose older pages beyond20, label the viewed revision
+and provide return-to-current. Missing legacy metrics remain unavailable, never fabricated.
+# Compact DESIGN export
+
+`GET /api/extracts/:id/design?revision=N&format=compact` returns a compact text
+projection of the verified proposal for that revision. It organizes normalized primitives,
+inferred semantic roles/scales and component mappings with evidence IDs, preserving
+source contexts and original CSS alias uses. A supplementary inventory is limited to
+64 candidates, with omissions disclosed and the complete proposal retained. It operates without rewriting historical artifacts or
+recollecting the source URL. Omit `format=compact` for the original stored DESIGN.md.
+If no proposal exists, the original export remains available.
+
+## Source tokenization versus generated tokens
+
+`design-score-v3` keeps seven equally weighted categories. `tokenization` now has the
+label `Tokenização da origem`: visual declarations using `var()` divided by all retained
+visual declarations, excluding custom-property definitions and computed styles. Whitespace
+after `var(` is accepted. Literals/constants remain in the denominator; no filtering was
+introduced to improve scores. Sampling and compiled CSS limit what this percentage means.
+
+`design_score.generated_token_quality` is a separate `generated-tokens-v1` assessment of
+the generated DESIGN.md. It never enters the Design Score average. Metrics expose passed,
+total, score and weight: 40% supported required roles/scales, 20% valid values/references,
+20% valid observation links/provenance, 20% candidate components with at least one supported
+mapping. The fixed 10 coverage slots are background, foreground, primary, primary text,
+body family, heading family, spacing, radii, borders and shadows. A missing slot earns no
+coverage credit; absence of a shadow does not necessarily indicate poor visual design.
+No denominator means unavailable and renormalized remaining weights; no tokens means null.
+This is structural usability of a bounded proposal, not source quality or visual fidelity.
+
+Detail `designMd`, the compact endpoint and the diagnostic use the current generated projection.
+Stored original revision bytes remain retrievable through the endpoint without `format=compact`.

package/templates/.agents/design/design-system-maker/NOTICE.md

@@ -0,0 +1,13 @@
+# Source reference and attribution
+
+The local source reference package `zaip-design-system-maker` 1.0.0 declares MIT and
+credits Alan Nicolas (`https://github.com/oalanicolas`); its README credits the original
+to the same author. These facts and source SHA-256 values were read by the authorized
+host and relayed on 2026-10-11 before UI adaptation. See SOURCE-PROVENANCE.json.
+
+No separate LICENSE file or exact upstream repository has been verified. This notice
+preserves the observed local declaration and credit; it does not invent an upstream
+license text, external grant verification or redistribution clearance. The original
+runtime/API here uses Node builtins and the project's portable URL extractor. No legacy
+LLM/provider/npx/post-hook, sibling launcher, extraction dataset or private output is
+copied or invoked. Frontend adaptation belongs to its separately assigned specialist.

package/templates/.agents/design/design-system-maker/README.md

@@ -0,0 +1,138 @@
+# ZAIP Design System Maker
+
+On Windows, open `zaip-design-system-maker.exe` in this directory. The launcher
+uses an existing Node >=22.16, starts the verified builtin-only runtime hidden,
+waits for authenticated readiness and requests the default browser at the local
+catalog. It never installs Node, invokes npx/providers, registers an OS protocol,
+scans fixed ports or restarts the computer. No sibling repository is required.
+
+If Node cannot be found in PATH, set `ZAIP_MAKER_NODE` to the full path of an
+existing supported `node.exe`, or pass `--node <absolute-path>`. An explicitly
+configured unavailable runtime produces a diagnostic rather than an install.
+`--no-browser` starts/reuses the service without requesting a browser. `--workspace`
+must identify the project containing this exact installed EXE/runtime. For normal
+use no arguments are needed. A failed browser request is reported; the collection
+and authenticated service remain recoverable by reopening the EXE.
+
+The catalog lists every saved extraction through pagination and opens its stable
+ID in Viewer. Create by URL submits a real bounded extraction job; completed and
+failed jobs have explicit status. Viewer exposes current/previous revisions,
+normalized evidence and the independent DESIGN.md proposal as text. Static CSS
+declarations and inferred token candidates are distinguished from optional actual
+host-supplied computed styles/screenshot evidence. A fixture is not a live-target
+proof. Nothing promotes extracted values into the central project design contract.
+
+Viewer also opens managed preview and diagnostic pages for the selected ID/revision.
+The details page presents the selected design's inferred visual system, colors and
+retained screenshot. The catalog filters by name, site, ID, theme and color; the
+viewer sidebar offers search. Short design codes identify saved references
+independently of their names.
+It offers DESIGN.md, Preview Render and the full diagnostic; reprocess/trash actions
+sit in the top toolbar, while specimens and revision history use native accordions.
+New DESIGN.md files group distinct token values without repeating the observation
+ledger. Existing revisions offer a compact read-only export; original bytes and full
+proposal/report evidence remain unchanged.
+The preview renders native demonstration components using that item's normalized,
+evidence-linked tokens for colors, typography, spacing, radii and shadows. Missing
+values use explicitly identified local fallbacks. Theme candidates are inferred from
+declared evidence; an active browser cascade is not claimed. The diagnostic view keeps
+the original neutral white diagnostic layout, with framed metric tiles, while live
+examples use the selected reference's tokens. Provenance and unknown capabilities
+remain explicit. Design Score uses seven categories: colors, typography, spacing,
+radii, source tokenization, local token lint and supported contrast pairs. Its
+equal-weight average excludes unavailable categories; it is a disclosed heuristic,
+not aesthetic judgment or accessibility certification. Source tokenization and
+generated-token quality are distinct. Historical extraction coverage and report
+exports keep their original meaning and values.
+Models derived from saved proposals/reports do not re-extract the URL or rewrite
+historical exports. Their 64 KiB projection budget may omit tail
+details with an explicit limitation; the original report and provenance remain intact.
+
+A failed collection is distinct from an older revision without a report. HTTP403 access
+challenges retain a redacted source/status/cause and an explicit retry; assisted review,
+opening the source browser or editing the URL never bypasses a challenge or silently
+substitutes another host. External HTML/CSS/scripts are never rendered at the app origin.
+
+The form selects **Abrir navegador local para extrair** by default when an existing
+browser is available, so dynamic sites receive rendered collection. Uncheck it for
+HTTP-only extraction; direct API requests without a mode still default to HTTP.
+This explicit mode uses an existing local Chromium browser with its own temporary
+profile. It does not copy personal browser sessions or install a browser. Complete
+an access challenge in that window if necessary; the job exposes opening, waiting
+and capture phases, a bounded wait and cancellation. A challenge that remains blocked
+produces a failed collection, never fabricated tokens or a report. Captured DOM/CSS
+feeds the evidence pipeline directly without repeating the failed HTTP page request.
+Reprocess uses the saved exact safe URL and the previous browser mode when supported;
+the action starts collection immediately with the saved URL and mode; its dialog
+shows the running job rather than requiring a separate confirmation. Polling retries refresh job state,
+without posting the extraction again. Failed captures expose a structured cause and
+explicit retry; a browser/runtime failure is not silently labeled a website HTTP403.
+Demonstration fonts use available local fallbacks when the source font bytes were not
+preserved. Native samples and captured styles remain evidence for that revision,
+not a guarantee of all source interactions or states.
+The proxy admits public hosts requested by the page and rejects unrelated browser
+background downloads. Capture can proceed after DOMContentLoaded and a short settling
+period instead of waiting indefinitely for late resources; the report discloses this.
+Large HTML documents retain a bounded sample of 500 nodes, with omitted elements
+reported, while subsequent stylesheets are still discovered. HTTP limits are 4 MiB
+per response, 8 MiB total, 10 seconds per request and 30 seconds total, up to 32 resources.
+
+The collector also looks for the site's favicon and a conventional `/favicon.ico`
+fallback. Validated raster/ICO bytes are saved with the immutable local revision and
+served through its verified asset route. Cards display that local favicon in a square
+frame, with initials when unavailable. Reprocess the saved URL to collect an icon for
+an older revision; historical files are not rewritten or silently fetched on viewing.
+
+## Session and data ownership
+
+The server binds port0 on 127.0.0.1. A kernel exclusion selected by platform and
+keyed to the physical workspace serializes startup; the collection has its own
+lifetime kernel exclusion. Windows uses named pipes. Other platforms use a
+loopback exclusion listener; an occupied authority never triggers a fallback.
+Two EXE invocations reuse only an authenticated compatible instance. The private
+lease `.local/design-system-maker/lease.json` binds workspace, installation, build,
+Node executable/version, host configuration hash and a random process instance.
+Its separate control secret is never exposed by `/api/session` or logged as browser
+metadata. A generic health response or a PID/port alone cannot establish ownership.
+Invalid or unprovable lease identity fails closed with a diagnostic. A dead process
+releases the kernel lock, permitting verified recovery without killing an unknown PID.
+
+Stop the identified service before upgrading managed sources or changing its Node
+or host configuration. This command authenticates the stored instance; it accepts
+no PID/port and cannot request an OS restart:
+
+```powershell
+node .agents/design/design-system-maker/runtime/stop.mjs --workspace .
+```
+
+The installed current build must verify before stop. An authenticated prior build
+from the same installation can then stop through its own control secret; a missing
+or tampered lease must be recovered from trusted local records, never guessed.
+Closing a browser tab does not stop the service. Reopening the EXE reuses it.
+
+Collection schema V1 lives in `data/`, project-owned and excluded from public
+templates, managed manifests and package inventories, together with uploads,
+exports/history and private local state. Runtime creates an empty collection only
+when absent. It preserves preferences and immutable entries/revisions/exports;
+rebuildable indices do not delete source history. Clean installation followed by
+first launch seeds this state. Upgrade, forced repair and rollback replace managed
+source/build assets and preserve project-owned collection/customization files.
+No schema migration is performed silently; future/corrupt schemas require explicit
+verified recovery. Back up and verify collection bytes before any authorized migration.
+
+See [API.md](API.md) for routes, request guards, trusted host-only fixture/capture
+configuration and extraction limits; [NOTICE.md](NOTICE.md) records local attribution.
+
+## Build identity
+
+`build.json` enumerates canonical template SHA-256 values and separately measured
+source-byte hashes where text normalization differs. Runtime accepts only these
+identified byte variants, verifies the EXE and binds readiness to `build_id`.
+Changing runtime, frontend or extractor source changes the build identity; skill
+guidance outside the app does not. Private data and frontend test fixtures are
+never build inputs. The launcher source is `launcher/Program.cs`; the maintainer
+build is `scripts/build-maker-launcher.ps1` with the canonical ZAIP PNG icon. The
+compiler emits the Windows GUI subsystem executable in this exact directory.
+Browser availability, a shell-open request and an independently observed tab are
+separate facts. Automated headless screenshots prove the served app, not a physical
+Explorer click or pixel fidelity to an external source.