@dcl-regenesislabs/artifacts 1.0.0 → 1.1.0

package/.claude/skills/dcl-artifacts/SKILL.md

@@ -0,0 +1,217 @@
+---
+name: dcl-artifacts
+description: Publish a static artifact (HTML page, demo, report, dashboard, mockup, slide deck, checklist, any folder of static files) to https://artifacts.dclregenesislabs.xyz and get a link back; push again to the same link to add a version. Use whenever someone asks to publish, host, deploy, share, update, or "give me a link to" a generated page or folder, or wants to send a visual result to someone who is not at this terminal. Also covers inspecting, listing and deleting artifacts, checkboxes that remember their state, and explaining how the public link works.
+---
+
+# Publishing artifacts to artifacts.dclregenesislabs.xyz
+
+Self-hosted artifact host on Cloudflare Workers + R2. Push a folder, get back a
+link. The link is a UUID that stays the same for life: pushing to it again adds
+a **version**, and readers can step back through versions from the bar at the
+top of the page.
+
+| | URL | Who can open it |
+| --- | --- | --- |
+| **team** (always) | `/{id}` | Only **@dclregenesislabs.xyz** and **@decentraland.org** accounts. They type their work email and paste the 6-digit code Cloudflare emails them. |
+| pinned version | `/{id}@2` | Same people; one specific version, frozen. |
+| **public** (optional) | `/p/{alias}` | Anyone holding the link. No login. |
+
+The public link is switched on and off **from the bar on the page**, by any
+person who can open it. **You cannot do it, and the CLI cannot do it** — that is
+deliberate. When the user wants a page public, publish it as usual and tell
+them: *open the link, flip "Public link" in the bar at the top, and copy the
+public URL it shows.* Never suggest a workaround.
+
+**If the CLI says `not signed in`, stop and tell the user to run
+`node cli/artifacts.mjs login`** — it opens a browser, they sign in with their
+work email, and it stores a token for them. You cannot do it for them, and
+there is no token in this file to fall back on.
+
+## Build the page
+
+**Default: the Regenesis data-report style —
+`references/regenesis-artifact-style.md`.** Read it before writing any markup. It is the house
+look for this host: the DCL brand palette with dark mode, the Inter type scale, the logo and
+header, the tab strip, the section-title/key-finding/card rhythm, the KPI-scorecard and
+pivot-table patterns, the hand-written SVG chart conventions (no chart library), and a list of
+the layout bugs that have actually broken these pages.
+
+It covers a page with one tab as happily as one with ten — a single-tab page is just the tab strip
+omitted. Start there for anything you would call a report, a scorecard, a dashboard, an analysis or
+a summary, which is nearly everything published here.
+
+The reference implementation is the shipped **LMT mobile-growth report**. When the guide is
+ambiguous, open the most recent one and copy the pattern.
+
+### Host rules — these apply to every page, whichever style you use
+
+**One file — in the published output.** Inline the CSS, the JS, the logo and small images (as
+data URIs). If you must add files, reference them **relatively** (`./chart.png`, never
+`/chart.png`) — artifacts are served under a path prefix. Entry point must be `index.html`, except
+a single-file push. Never load a stylesheet from another artifact. Never name a top-level file
+starting with `__` (reserved).
+
+*Authoring may differ from output.* The legacy template keeps its CSS and JS in
+`templates/artifact/assets/` and `artifacts.mjs new` inlines them at scaffold time by replacing
+the `<link>`/`<script>` markers, so what you publish is still one file. If you edit that template,
+**leave those two marker lines exactly as they are** — the CLI throws if it cannot find them.
+
+**The bar is not yours to build.** The host injects a bar at the top of every gated page: name,
+version picker, the public switch, copy link. Do not add a navbar, a version number, a "last
+updated" line or a share button to the page itself — they duplicate the bar and go stale. Do not
+rely on it either: the public link and the file itself have no bar.
+
+**Checkboxes that stick.** Any `<input type="checkbox" data-persist="some-key">` remembers its
+state on the host: tick it, reload, open it elsewhere, it stays ticked, and the bar shows who
+ticked it and when. Use it whenever the page has things to complete or confirm. The key is the
+identity — a short, stable slug (`deploy-staging`, `legal-signoff`), unique within the page, and
+**unchanged across versions** or the ticks are lost. Only team members can change them; the public
+link shows them read-only. This is a host feature, not a template feature — it works in any page.
+
+Keep running text under ~78 characters, and put wide things (tables, code) in their own scrolling
+container so the body never scrolls sideways.
+
+### Prose template — for documents, not reports
+
+```bash
+node cli/artifacts.mjs new ./path/to/dir --name "Page title"
+```
+
+`templates/artifact/index.html` is **no longer the default**, but it is not off-brand and it is not
+going away: it now carries the **same house palette, Inter type, radius and dark mode** as the
+report style (`assets/dcl.css` was repainted to the house tokens). One visual language, two
+layouts — this is the prose layout.
+
+Reach for it when a page is genuinely a **document** whose value is in the writing — a spec, a
+runbook, a long memo — and the report style's tabs and cards would fight the content. Its blocks:
+
+| Need | Use |
+| --- | --- |
+| The one thing the reader must leave with | `.callout` (filled); `.callout.ok / .warn / .bad / .info` |
+| A caveat, a dependency, context | `.note` (rail); same colour modifiers |
+| Tabular data | `.tblwrap > table`; cells `.n` name, `.t` short, `.src` file refs, `.r` numbers; `.yes / .no / .chg` |
+| A few facts about one thing | `dl.kv` |
+| Named things with attributes | `.grid2 / .grid3 > .card.ok / .warn / .bad / .info / .plain` with `.card-h > .name + .badge + .lang` |
+| Figures that are the point | `.grid3 > .stat > .v + .l` |
+| Inline state | `.pill.ok / .warn / .bad / .accent / .info`, or outlined `.tag` |
+| A real sequence (rollout, procedure) | `ol.phases` — never for an unordered list |
+| Things to tick off | `ul.checklist > li > label > input[type=checkbox][data-persist="key"]` |
+| Commands, output | `pre > code` with spans `.c` comment, `.k` keyword, `.o` output — a Copy button is added by itself |
+| A code change | `.path` + `.split > .col > .colhead.before/.after + .code > .row.del/.add/.ctx/.pad` |
+
+Write inside `.wrap`; leave the big `<style>` and `<script>` alone. The one per-page knob is
+`--accent` / `--accent-soft` in the *small* `<style>` block after them.
+
+Skip both when the page is an app or demo whose own design is the point.
+
+## Publish
+
+With the page in a directory (`index.html` is the entry point):
+
+```bash
+node cli/artifacts.mjs push ./path/to/dir --name "short label"
+```
+
+The URL is printed on stdout — progress goes to stderr, so
+`URL=$(... push ./dir)` captures just the link. **Hand it over exactly as
+printed** — `https://artifacts.dclregenesislabs.xyz/{id}`, no trailing slash,
+nothing appended — and mention it needs a work-email login the first time they
+open it. (A multi-file folder redirects itself to `/{id}/` when opened; that's
+fine, don't pre-empt it.) `--name` is what the bar shows; make it a real title.
+
+## Update — push a new version
+
+Same link, new content. Pass the artifact's URL (or bare id) as `--id`:
+
+```bash
+node cli/artifacts.mjs push ./path/to/dir --id https://artifacts.dclregenesislabs.xyz/3f2b9c1e-4d5a-4b6c-8e7f-9a0b1c2d3e4f
+```
+
+- The link does not change. Readers get the new version; the bar lets them
+  open older ones, and `/{id}@1` pins the first.
+- Identical content records nothing (the CLI says so). Only changed files are
+  uploaded.
+- Checkbox ticks survive a new version as long as the `data-persist` keys do.
+- When you have iterated on a page in this session, **always** push with
+  `--id` — a fresh push makes a second, unrelated link and splits the history.
+  If the user gives you an artifact link and asks for changes, that link is
+  the `--id`.
+- `--name` on an update renames it; omit it to keep the name.
+
+Variations:
+
+```bash
+# a single file becomes a one-file artifact served at the bare URL
+... push ./report.html --name "weekly report"
+
+# several new artifacts in one go (omit --name and --id; each folder gets its own link)
+... push ./demos/*/
+
+# machine-readable result: {id, url, version, unchanged, name, files, bytes, hasIndex}
+... push ./dir --json
+```
+
+## Inspect, list, delete
+
+```bash
+node cli/artifacts.mjs info https://artifacts.dclregenesislabs.xyz/3f2b9c1e-4d5a-4b6c-8e7f-9a0b1c2d3e4f
+node cli/artifacts.mjs ls
+node cli/artifacts.mjs rm   https://artifacts.dclregenesislabs.xyz/3f2b9c1e-4d5a-4b6c-8e7f-9a0b1c2d3e4f
+```
+
+`info` shows the name, every version (when, by whom) and whether the public
+link is on. `ls` is the only listing that exists — the web has none. `rm`
+deletes every version, the checkbox state and the public link; confirm with
+the user first, it cannot be undone.
+
+## What to build
+
+- Start from `new` unless there is a reason not to (see "Build the page").
+- Entry point **must** be `index.html` (a single-file push is the exception).
+- Reference assets **relatively** — `./assets/app.js`, never `/assets/app.js`.
+  Artifacts are served under a path prefix, so absolute paths break.
+- Everything must be static. No server, no build step at request time — bundle or
+  inline what you need, or load libraries from a CDN.
+- Per-file limit 25 MB; up to 2000 files per artifact.
+- `.git`, `node_modules`, `.DS_Store`, `.env` and `.dev.vars` are skipped
+  automatically (pass `--all` to include them).
+
+## When to use this
+
+Use it when the result is meant to be **looked at, shared, or worked through** —
+a demo, a report, a chart, a mockup, a checklist the team will tick off,
+anything the user wants to open on their phone or send to a teammate. For code
+the user will edit, just write files locally instead.
+
+## Things worth knowing
+
+- A `/{id}` URL is safe to paste in team channels; it still needs a work email.
+- A `/p/{alias}` URL is not. It is unauthenticated and stays live until someone
+  switches it off in the bar. **Never publish credentials, private keys, or
+  customer data** on a page that might be made public.
+- The bar records who switched the public link on, and who ticked each box.
+- All artifacts share one origin, so a published page can read another artifact's
+  `localStorage` and call its in-page API. Do not publish pages that run
+  untrusted third-party script.
+- Publishing is effectively permanent until someone runs `rm`. Confirm with the
+  user before publishing anything that was not obviously meant to be shared.
+
+## Raw HTTP (only if the CLI is unavailable)
+
+All calls take `Authorization: Bearer <token>`, using the token from
+`~/.config/dcl-artifacts/credentials.json` (`hosts` -> the host -> `token`).
+`/_api/*` is exempt from the Access gate and guarded by the bearer alone. `id` is a UUID v4 you mint;
+`base` is the version number `status` reported (0 for a new artifact):
+
+```
+GET    /_api/artifacts                        -> {artifacts:[...]}
+GET    /_api/artifacts/{id}                   -> name, versions, visibility, public link
+POST   /_api/artifacts/{id}/status            body: {files:[{path,size,sha256}]} -> {exists, current, missing:[sha256]}
+PUT    /_api/artifacts/{id}/blobs/{sha256}    body: raw bytes (must hash to the path)
+POST   /_api/artifacts/{id}/commit            body: {files, base, name?, author?} -> {id, url, version}
+DELETE /_api/artifacts/{id}
+```
+
+There is no endpoint that makes an artifact public. `shared/artifact-id.js` in
+this repo is the reference for ids, the version content hash, and manifest
+validation.

package/.claude/skills/dcl-artifacts/references/regenesis-artifact-style.md

@@ -0,0 +1,498 @@
+# Regenesis data-report style
+
+**The default look for pages on this host.** Read this before writing any markup.
+
+It covers a page with one tab as happily as one with ten, so it is the starting point for anything
+you would call a report, a scorecard, a dashboard, an analysis or a summary — nearly everything
+published here. The older IBM Plex prose template (`templates/artifact/index.html`) is stale and
+kept only for existing pages and for genuine long-form documents; see `SKILL.md`.
+
+Everything below was extracted from the shipped **LMT2 Mobile Growth** report, which is the
+reference implementation, and is reproduced here so the guide is self-contained.
+
+## Relationship to `assets/dcl.css`
+
+**This guide is authoritative.** `templates/artifact/assets/dcl.css` — the prose template's
+stylesheet — has been repainted to match it, so the two are now **one visual language in two
+layouts**: this guide is the *report* layout (tabs, KPI scorecards, charts), `dcl.css` is the
+*prose* layout (callouts, notes, phases, checklists, code diffs).
+
+Aligned, and to be kept aligned:
+
+| Token in `dcl.css` | Value | This guide |
+|---|---|---|
+| `--ground` | `#f9f9f7` | `--page` |
+| `--surface` | `#fcfcfb` | `--surface` |
+| `--ink` | `#0b0b0b` | `--ink` |
+| `--muted` | `#52514e` | `--ink-2` |
+| `--hairline` | `#e1e0d9` | `--grid` |
+| `--accent` / `--bad` | `#FF2D55` | `--dcl-red` / `--critical` |
+| `--ok` | `#0ca30c` | `--good` |
+| `--warn` | `#fab219` | `--warning` |
+| `--info` | `#2a78d6` | `--desktop` |
+| `--font-sans` / `--font-mono` | Inter | Inter |
+| `--radius` | `14px` | card radius |
+| `--page-width` | `920px` | `.wrap` max-width |
+
+**If you change a colour here, change it in `dcl.css` too.** They drifting apart is the failure
+mode this alignment exists to prevent.
+
+### The two name collisions are resolved — don't reintroduce them
+
+`dcl.css` previously used `--page` for a **length** and `--line` for a **hairline colour**, while
+this guide uses `--page` for a **colour** and `--line` for the **red trend-line**. Loading both
+broke layout (`max-width: var(--page)` resolved to a colour) and turned every border brand red.
+
+`dcl.css` now uses **`--page-width`** and **`--hairline`**, so the names no longer clash. Do not
+rename them back, and do not introduce a `--page` or `--line` into `dcl.css`.
+
+Sharing a palette still does **not** mean sharing a page: a page is a report *or* a document. Do
+not load both stylesheets or mix their class vocabularies.
+
+### Existing published pages are unaffected
+
+`artifacts.mjs new` inlines `dcl.css` into the scaffolded `index.html`, and publishing uploads that
+file's bytes. **Every already-published page carries its own frozen copy of the CSS**, so editing
+the template repaints *future* scaffolds only. Nothing that is already live changes appearance, and
+no `data-persist` keys are at risk.
+
+## Host integration
+
+Three things come from the host, not from this stylesheet, and apply to every page:
+
+- **The bar** — the host injects name, version picker, public switch and copy link at the top of
+  a gated page. Never build your own navbar, version line or share button. Never depend on it
+  either: the public link and the downloaded file have no bar.
+- **Persisted checkboxes** — `<input type="checkbox" data-persist="stable-slug">` keeps its state
+  on the host across reloads, viewers and versions, and the bar records who ticked it. This works
+  in **any** page, including one built with this guide. Keep the key stable across versions or the
+  ticks are lost.
+- **Relative asset paths only** (`./chart.png`). Artifacts are served under a path prefix.
+---
+
+## 1. The one-file rule
+
+One `.html` file. Inline the CSS, the JS, the logo and any images (as data URIs). No build step,
+no external stylesheet, no framework. Two consequences worth internalising:
+
+- **Charts are hand-written SVG.** No charting library. There is an `el()` helper (below) and
+  every chart is ~60 lines of explicit geometry. This is deliberate: it survives being pasted
+  anywhere and never breaks on a CDN change.
+- **A published page is frozen.** Numbers are literals in the JS, not queries. Anything that will
+  be re-run must be re-queried and re-pasted, so keep the data arrays together at the top of each
+  chart block with a comment saying when they were pulled and from what.
+
+## 2. Type
+
+```css
+@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800;900&display=swap');
+font-family: "Inter", system-ui, -apple-system, "Segoe UI", sans-serif;
+```
+
+Inter throughout. Numerals are always `font-variant-numeric: tabular-nums` in tables and chart
+labels so columns line up. Monospace is *Inter* too (`"Inter", monospace`) — there is no separate
+mono face; the label just gets tabular figures.
+
+| Role | Size | Weight |
+|---|---|---|
+| `h1` page title | 28px | 800 |
+| `.kpi-section-title` | 20px | 700 |
+| `.kpi-keyfinding` (the sentence under a title) | 17.5px | 400 |
+| `.chart-title` | 14.5px | 700 |
+| `.card-title` | 16px | 700 |
+| body / `.kf-list li` | 14px | 400 |
+| table cells | 12.5-13px | 400 |
+| `.kpi-metric-name` | 13.5px | 700 |
+| `.kpi-metric-sub`, footnotes | 11-12px | 400 |
+| `.page-eyebrow`, `.page-byline` | 10.5px | 700, `letter-spacing: .09em` |
+
+**Precision**: one decimal on every metric and percentage ("4.2 min", "10.4%"). Currency keeps
+two ("$0.60"). Round at display time only.
+
+## 3. Palette
+
+Copy this block verbatim. It is theme-aware: light on bare `:root`, dark under both
+`prefers-color-scheme` and an explicit `[data-theme="dark"]`.
+
+```css
+  :root {
+    color-scheme: light;
+    --page:        #f9f9f7;
+    --surface:     #fcfcfb;
+    --ink:         #0b0b0b;
+    --ink-2:       #52514e;
+    --ink-muted:   #898781;
+    --grid:        #e1e0d9;
+    --axis:        #c3c2b7;
+    --border:      rgba(11,11,11,0.10);
+    --up:          #006300;
+
+    --dcl-red:     #FF2D55;
+    --dcl-purple:  #39055C;
+    --dcl-purple-2:#A524B3;
+
+    --desktop:     #2a78d6;
+    --mobile:      #008300;
+    --line:        #FF2D55;
+
+    --good:        #0ca30c;
+    --warning:     #fab219;
+    --serious:     #ec835a;
+    --critical:    #FF2D55;
+
+    --tier-high:   #2a78d6;
+    --tier-mid:    #1baf7a;
+    --tier-low:    #eda100;
+    --tier-unscored: #ababa3;
+    --tier-no-telemetry: var(--critical);
+
+    --pt1: #d7ecd2;
+    --pt2: #a9d69f;
+    --pt3: #79bd6a;
+    --pt4: #429b30;
+    --pt5: #196b0d;
+    --scpt1: #FF2D55;
+    --scpt2: #f3722c;
+    --scpt3: #f9c74f;
+    --scpt4: #90be6d;
+    --scpt5: #39ff14;
+
+    --card-shadow: 0 1px 2px rgba(11,11,11,0.04), 0 8px 24px rgba(11,11,11,0.05);
+    --head-label-ink: color-mix(in srgb, #ffffff 68.5%, var(--ink-muted));
+    --sources-ink: var(--ink-muted);
+    --sources-ink-strong: var(--ink-2);
+  }
+```
+
+Dark mode redefines the same tokens (note the **purple gradient page background** — dark mode is
+not just an inverted light mode):
+
+```css
+  :root[data-theme="dark"] {
+    color-scheme: dark;
+    --page:        #0d0d0d;
+    --page-gradient: linear-gradient(to right, #C640CD 0%, #691FA9 100%);
+    --surface:     #1a1a19;
+    --ink:         #ffffff;
+    --ink-2:       #c3c2b7;
+    --ink-muted:   #898781;
+    --grid:        #2c2c2a;
+    --axis:        #383835;
+    --border:      rgba(255,255,255,0.10);
+    --up:          #0ca30c;
+
+    --dcl-red:     #FF2D55;
+    --dcl-purple:  #C77DFF;
+    --dcl-purple-2:#D68BFF;
+
+    --desktop:     #3987e5;
+    --mobile:      #008300;
+    --line:        #FF2D55;
+
+    --good:        #0ca30c;
+    --warning:     #fab219;
+    --serious:     #ec835a;
+    --critical:    #FF2D55;
+
+    --tier-high:   #3987e5;
+    --tier-mid:    #199e70;
+    --tier-low:    #c98500;
+    --tier-unscored: #6b6b64;
+    --tier-no-telemetry: var(--critical);
+
+    --pt1: #1c3517;
+    --pt2: #2c5a22;
+    --pt3: #3e8830;
+    --pt4: #55b840;
+    --pt5: #74e858;
+    --scpt1: #FF2D55;
+    --scpt2: #f3722c;
+    --scpt3: #f9c74f;
+    --scpt4: #90be6d;
+    --scpt5: #39ff14;
+
+    --card-shadow: 0 1px 2px rgba(0,0,0,0.3), 0 8px 24px rgba(0,0,0,0.35);
+    --head-label-ink: color-mix(in srgb, #ffffff 68.5%, var(--ink-muted));
+    --sources-ink: #ffffff;
+    --sources-ink-strong: #ffffff;
+  }
+```
+
+Under `@media (prefers-color-scheme: dark)` guard the same overrides with
+`:root:where(:not([data-theme="light"]))`.
+
+**Token meanings that matter**
+
+- `--dcl-red #FF2D55` — the brand accent. Selected tab underline, chart trend lines, the
+  "critical" status. Use sparingly; it is loud.
+- `--mobile #008300` / `--desktop #2a78d6` — the platform pair. **Never swap them**; every chart
+  in the family uses green = mobile, blue = desktop.
+- `--good / --warning / --serious / --critical` — status scale for KPI chips and heat scales.
+  `--critical` is the same red as the brand accent by design.
+- `--pt1..--pt5` — a 5-step green ramp for playtime buckets (light → dark = short → long).
+- `--tier-*` — device tiers. `--tier-no-telemetry` is deliberately `--critical`: missing telemetry
+  is a problem, not a neutral category.
+
+**Dark-mode text override.** The purple gradient background needs sub-headers, tab labels and the
+footer forced to `--ink` (white), or they inherit muted grey and vanish:
+
+```css
+:root[data-theme="dark"] .sub, :root[data-theme="dark"] .tab-btn,
+:root[data-theme="dark"] footer, :root[data-theme="dark"] footer a { color: var(--ink); }
+```
+
+## 4. Page shell
+
+```html
+<div class="wrap">              <!-- max-width 920px; padding 40px 24px 64px; flex column, gap 28px -->
+  <header class="page-head">    <!-- eyebrow + h1 + sub | logo + byline -->
+  <div class="tabs" role="tablist">
+  <div class="tab-panel" role="tabpanel" id="tab-panel-N" hidden>
+```
+
+**Header**: left column is `.page-eyebrow` (uppercase project tag) → `h1#page-title` →
+`p.sub#page-sub`; right column is the 40x40 logo above `.page-byline` ("by @Name"). The h1 and sub
+are **driven by the tab machinery**, not static — see §5.
+
+**Logo** (paste as-is into `.page-head-logo`):
+
+```html
+<svg viewBox="0 0 90 90" fill="none" xmlns="http://www.w3.org/2000/svg"><path fill-rule="evenodd" clip-rule="evenodd" d="M45 89.9999C69.8528 89.9999 89.9999 69.8528 89.9999 45C89.9999 20.1472 69.8528 0 45 0C20.1472 0 0 20.1472 0 45C0 69.8528 20.1472 89.9999 45 89.9999Z" fill="url(#dcl0)"/><path fill-rule="evenodd" clip-rule="evenodd" d="M18 80.9996C25.515 86.6471 34.875 89.9996 45 89.9996C55.125 89.9996 64.485 86.6471 72 80.9996H18Z" fill="#FF2D55"/><path fill-rule="evenodd" clip-rule="evenodd" d="M9 71.9996C11.565 75.397 14.603 78.435 18 80.9996H72C75.398 78.435 78.435 75.397 81 71.9996H9Z" fill="#FFA25A"/><path fill-rule="evenodd" clip-rule="evenodd" d="M60.368 62.9997H3.758C5.153 66.2172 6.93 69.2322 9 71.9997H60.39V62.9997H60.368Z" fill="#FFC95B"/><path fill-rule="evenodd" clip-rule="evenodd" d="M31.883 29.25V63H60.008L31.883 29.25Z" fill="url(#dcl1)"/><path fill-rule="evenodd" clip-rule="evenodd" d="M3.758 63H31.883V29.25L3.758 63Z" fill="white"/><path fill-rule="evenodd" clip-rule="evenodd" d="M60.368 47.25V72H81L60.368 47.25Z" fill="url(#dcl2)"/><path fill-rule="evenodd" clip-rule="evenodd" d="M39.757 72H60.367V47.25L39.757 72Z" fill="white"/><path fill-rule="evenodd" clip-rule="evenodd" d="M60.368 40.5C66.58 40.5 71.618 35.463 71.618 29.25C71.618 23.037 66.58 18 60.368 18C54.154 18 49.118 23.037 49.118 29.25C49.118 35.463 54.154 40.5 60.368 40.5Z" fill="#FFC95B"/><path fill-rule="evenodd" clip-rule="evenodd" d="M31.882 22.5C34.989 22.5 37.507 19.981 37.507 16.875C37.507 13.768 34.989 11.25 31.882 11.25C28.776 11.25 26.257 13.768 26.257 16.875C26.257 19.981 28.776 22.5 31.882 22.5Z" fill="#FFC95B"/><defs><linearGradient id="dcl0" x1="45" y1="-18.64" x2="-18.64" y2="45" gradientUnits="userSpaceOnUse"><stop stop-color="#FF2D55"/><stop offset="1" stop-color="#FFBC5B"/></linearGradient><linearGradient id="dcl1" x1="31.873" y1="29.25" x2="31.873" y2="63" gradientUnits="userSpaceOnUse"><stop stop-color="#A524B3"/><stop offset="1" stop-color="#FF2D55"/></linearGradient><linearGradient id="dcl2" x1="60.36" y1="47.25" x2="60.36" y2="72" gradientUnits="userSpaceOnUse"><stop stop-color="#A524B3"/><stop offset="1" stop-color="#FF2D55"/></linearGradient></defs></svg>
+```
+
+**Cards**: `section.card` — `--surface` background, 1px `--border`, `border-radius: 14px`,
+`box-shadow: var(--card-shadow)`, padding `22px 22px 18px`. Every chart and table lives in one.
+
+## 5. Navigation
+
+A single non-wrapping tab strip that scrolls sideways rather than reflowing to two rows.
+
+```html
+<button class="tab-btn" role="tab" id="tab-btn-3" aria-selected="false"
+        aria-controls="tab-panel-3" data-idx="3"><span class="tab-icon">⏳</span>Playtime</button>
+```
+
+```js
+const btns = Array.from(document.querySelectorAll(".tab-btn"));
+const panels = [0,1,2].map(i => document.getElementById("tab-panel-" + i));
+const meta = [{ title: "...", sub: "" }];               // one per panel index
+function select(idx) {
+  btns.forEach(b => b.setAttribute("aria-selected", String(Number(b.dataset.idx) === idx)));
+  panels.forEach((p,i) => { p.hidden = i !== idx; });
+  titleEl.textContent = meta[idx].title;                 // the h1 follows the tab
+  subEl.innerHTML = meta[idx].sub; subEl.hidden = !meta[idx].sub;
+}
+```
+
+- `data-idx` is the panel index and **need not match strip order** — the strip is ordered for the
+  reader, the indices for the code.
+- Selected tab: `--ink` text + 2px `--dcl-red` bottom border. Hover: 7% ink tint + a 45%-alpha red
+  underline previewing the selection (colour alone is not enough, because dark mode forces all tab
+  labels to the same ink).
+- **Emoji tab icons**, one per tab, in a `.tab-icon` span (`margin-right: 6px`, scales 1.14x on
+  hover). Reuse the same emoji anywhere else that metric appears — section headings
+  (`.sec-icon`) and KPI table rows (`.kpi-metric-icon`) — so the reader recognises it across tabs.
+- Cross-tab links use `data-jump="N"` + a `window.__selectTab(n)` that also scrolls to top.
+
+## 6. Content blocks
+
+**Section title → key finding → card.** This trio is the spine of every tab:
+
+```html
+<div class="kpi-section-title"><span class="sec-icon">🤝</span>Social Behavior</div>
+<div class="kpi-keyfinding">The one sentence the reader must leave with, <b>numbers bolded</b>.</div>
+<section class="card"> ... </section>
+```
+
+The key finding is a **claim, not a caption** — it states what the chart proves, in prose, with
+the load-bearing figures in `<b>`. Never write "the chart below shows…".
+
+**Collapsible section** — same trio, wrapped, for secondary material. Ships **closed** (no `open`
+attribute) so a tab opens condensed:
+
+```html
+<details class="kpi-collapse">
+  <summary class="kpi-section-title">Secondary cut</summary>
+  <div class="kpi-keyfinding">…</div>
+  <section class="card">…</section>
+</details>
+```
+
+The caret is a CSS `::before` `\25B8` at `font-size: 1.44em; line-height: .7` that rotates 90° when
+open. Inside a `<details>` the children are ordinary blocks, so the flex gap and the key finding's
+negative margins do not apply — spacing is set explicitly by
+`details.kpi-collapse > .kpi-keyfinding { margin: 14px 2px 16px; }`.
+
+**Stat tiles** for a few headline figures: `.stat-row > .stat-tile > .stat-value + .stat-label`.
+Variants `.stat-row-tight` and `.stat-row-sm` for denser rows.
+
+**Findings / Recommendations** side by side: `section.card.kf-two-col` with two `.kf-block`s, each
+led by `.kf-block-title.kf-find` (blue dot) or `.kf-rec` (green dot). Collapses to stacked under
+720px, and the vertical divider becomes a horizontal rule.
+
+**Sources**: every tab ends with `<hr class="sources-divider">` and a
+`<details class="sources-dropdown"><summary>See Sources</summary>` holding a two-column table
+(Chart / Analysis | Source & Query). Rendered by a `renderSources(tableId, rows)` that
+early-returns if the table is absent, so a tab with no queries can simply omit it.
+
+## 7. Tables
+
+`table.kpi-table` (fixed layout, `border-separate`, `border-spacing: 0`).
+
+- Header: centred, 14px/700, `--ink`, 1px `--border` bottom.
+- Cells: right-aligned by default; the metric cell and status cell are left-aligned.
+- Metric cell holds `.kpi-metric-name` (+ optional `.kpi-metric-icon`) and `.kpi-metric-sub`.
+- `.pivot` variant for segment comparisons: `table-layout: auto`, centred cells, a
+  **`.pivot-overall` reference column styled distinctly and excluded from best/worst ranking**.
+- `td.pivot-best` green tint / `td.pivot-worst` red tint for the winner and loser in each row.
+- Per-column **heat scale** (`heatStyle(col, value)`) tints the highest value green and the lowest
+  red *by magnitude only* — say so in a footnote, because a low value is not always "bad".
+- Wide tables live in `.pivot-wrap` / `.table-scroll` (`overflow-x: auto`). **The page body must
+  never scroll sideways.**
+- Footnotes go in `.kpi-footnote-group > .kpi-footnote` under the table, italic, 12px.
+
+**Status chips** (`.kpi-status.status-good|review|shortfall`): a coloured dot + text on a 14%-alpha
+background of the same colour. A second `.kpi-growth-chip` sits under the first for a
+"vs previous test" delta. **Always render the plain-language read** ("20% below target"), never a
+bare signed number — the sign's meaning is metric-dependent (lower is better for cost and crash
+rate, worse for engagement).
+
+**Dedup rule.** A "platform share" style row is deduplicated (an entity present on both sides
+counts once in the total), so the two shares legitimately sum to slightly over 100%; a stacked
+share **chart** divides by the sum and is exactly 100%. When both appear together the table needs
+a footnote saying so. Never reconcile them by changing a denominator.
+
+## 8. Charts
+
+Hand-written SVG. The helper — **note `createElementNS`**:
+
+```js
+const NS = "http://www.w3.org/2000/svg";
+function el(tag, attrs, parent) {
+  const e = document.createElementNS(NS, tag);          // document.createElement() silently fails
+  for (const k in attrs) e.setAttribute(k, attrs[k]);
+  if (parent) parent.appendChild(e);
+  return e;
+}
+```
+
+**Structure**
+
+```html
+<section class="card">
+  <div class="chart-title">Monthly players &amp; mobile share</div>
+  <div class="legend"><span class="legend-item"><span class="swatch" style="background:var(--mobile)"></span>Mobile</span></div>
+  <div class="chart-wrap">
+    <div class="chart-scroll"><svg id="chartN" viewBox="0 0 860 340" width="860" height="340"></svg></div>
+    <div class="tooltip" id="tooltipN"></div>
+  </div>
+  <details class="table-toggle"><summary>View data table</summary>…</details>
+</section>
+```
+
+- `viewBox` + `width`/`height` **and** any `H`/`W` constant in the JS must be changed together, or
+  the drawing scales wrong.
+- `.chart-scroll svg { width: 100%; height: auto; }` — charts are authored at a fixed logical size
+  and scale down.
+- Every chart offers a `.table-toggle` "View data table" with the underlying numbers.
+
+**Chart type conventions**
+
+| Class | Use |
+|---|---|
+| `.tick-label` | axis values, 11px, `--ink-2` |
+| `.month-label` | x-axis categories, same treatment |
+| `.axis-title` | 10.5px uppercase, `.03em`, `--ink-muted` |
+| `.value-label` | data labels, 10px, tabular |
+| `.value-label.on-line` | label on a trend line, coloured `--line` |
+| `.gridline` | **`display: none`** — gridlines are off by default |
+| `.baseline` | the single axis rule, `--axis`, 1px |
+| `.bar.mobile` / `.bar.desktop` | the platform pair |
+| `.share-line` + `.share-dot` | the red overlay trend line and its markers |
+
+- **Both** `viewBox` units and CSS px appear; class-driven label sizes need a scoped override
+  (`#chartN .tick-label { font-size: 14.3px }`) while inline sizes are attributes on the element.
+- Tooltips: absolutely positioned `.tooltip` inside `.chart-wrap`, `.show` toggles opacity,
+  positioned from `getBoundingClientRect()` scaled by `cx / W * bounds.width`.
+- Two-line category labels are `<tspan x=cx dy=0>` + `<tspan x=cx dy=12>`; **raise `dy` whenever
+  you raise the font size** or the lines collide.
+- **Copy-paste hazard**: charts are often cloned. Before find-and-replacing any geometry or font
+  size, check whether the same string exists in another chart's block and anchor the replacement
+  on that chart's `svg` variable.
+
+**Milestone highlight**: to call out one column, draw a rounded `rect` behind it first
+(`color-mix(in srgb, var(--ink) 6%, transparent)` fill, `--border` stroke) so the bars sit on top.
+Any label lifted out of the box must be re-checked against the top margin after a height change.
+
+**Funnel bar width**: `Math.min(cap, bandW * ratio)`. The **cap usually binds** — raising only the
+ratio does nothing. Change both.
+
+**Broken axis**: when a few outliers stretch a scale, give the dense range ~75-85% of the width
+and compress the tail into the rest, with a twin-slash break marker on the axis and an explicit
+tick list (an every-N loop will crowd the compressed side).
+
+## 9. Diagrams
+
+For a non-charted diagram (a phased timeline, a gated pipeline), use CSS grid + absolutely
+positioned markers rather than SVG — text wraps natively and it stays responsive:
+
+- N equal columns, an absolutely positioned rail at the dot centres
+  (`top = padding-top + dot-radius`), markers placed by percentage (`left: 25%` for the boundary
+  between 4 columns).
+- Verdict colour on the marker: `--good` where a gate is cleared, `--critical` where it is not.
+- **Everything is coupled to the rail.** If you change the top padding you must move the rail, the
+  marker bars and any band together.
+- Under the breakpoint, hide the rail and markers and reflow the items to a 2-column grid — the
+  percentage positioning is meaningless once columns stack.
+
+## 10. Responsive + theme rules
+
+- Relative units, flex/grid, `max-width: 100%` on images.
+- Wide content scrolls inside its own container; the body never scrolls horizontally.
+- Define the **complete** light palette on bare `:root`; only redefine tokens in the dark blocks.
+  Never give a colour its only definition inside a media query.
+- Give `body` an explicit token background.
+- Breakpoints in use: **720px** (two-col → stacked), **780px** (diagram rails off), **860px**
+  (split cards stack).
+
+## 11. Embeds
+
+**A third-party `<iframe>` is blocked in Claude Artifacts.** The viewer's CSP admits only the
+artifact's own files, Google Fonts and a few script CDNs; Drive, YouTube and everything else
+render blank and the publish step warns "loads N embedded frames from other websites". The same
+page **works on `artifacts.dclregenesislabs.xyz`**. So: link out for Claude Artifacts, embed only
+when the DCL host is the target — and say which you are building for.
+
+**Google Drive video embed** (`/preview`, not `/view`): the player has a minimum layout width, so
+in a narrow slot it renders only its left letterbox bar with the video cut off. Fix by
+over-sizing and centring the iframe:
+
+```css
+.video-frame { position: relative; overflow: hidden; }   /* the visible box */
+.video-frame iframe {
+  position: absolute; top: 50%; left: 50%;
+  width: 400%; height: 100%;                             /* 4x the box, centred */
+  transform: translate(-50%, -50%); border: 0;
+}
+```
+
+The video is sized by the player's height, so in a 9/16 box it comes out exactly box-width and the
+black bars crop away symmetrically.
+
+## 12. Gotchas that cost real time
+
+1. **`document.createElement` for SVG** produces an element that appends without error and never
+   renders. Always `createElementNS`.
+2. **CSS specificity**: an element carrying two classes needs both in the selector.
+   `.kf-conclusion { margin-top: 18px }` loses to a later `.kf-recap { margin: 0 }`; it must be
+   `.kf-recap.kf-conclusion`.
+3. **Margin shorthand resets**: a later `margin:` shorthand silently wipes an earlier
+   `margin-top`. Keep a block's margin in one declaration.
+4. **`aspect-ratio` vs flex**: a flex child that must stretch needs `min-height: 0` (or
+   `min-width: 0` in a row) or it refuses to shrink and forces the container.
+5. **`align-items: flex-start`** on a flex row means a column only grows to its own content — a
+   child can never reach the container's height. Use `stretch`.
+6. **Emoji in JS** are written as `\u` escapes throughout, for consistency and to avoid encoding
+   surprises.
+7. **A `<details>` child is not a flex item** of the tab panel, so the panel's `gap` and any
+   negative margins tuned against it stop applying inside.

package/README.md

@@ -127,39 +127,29 @@ Claude picks all of this up through the project skill in
 
 ## Install the skill (one line)
 
-macOS / Linux:
-
 ```bash
-curl -fsSL https://artifacts.dclregenesislabs.xyz/install.sh | bash
-```
-
-Windows (PowerShell):
-
-```powershell
-irm https://artifacts.dclregenesislabs.xyz/install.ps1 | iex
+npx @dcl-regenesislabs/artifacts setup
 ```
 
-No secret in either line. `scripts/install.sh` / `scripts/install.ps1` are
-served by the Worker at a public path together with `dist/dcl-artifacts.tgz` —
-the CLI, the shared id module, the house template and the skill with its style
-reference, built by `scripts/build-dist.mjs` before every `npm run dev` /
-`npm run deploy` and checked to contain nothing token-shaped. The installer
-unpacks the tarball into `~/.dcl-artifacts`, writes the skill to
-`~/.claude/skills/dcl-artifacts/` with that path filled in, and then runs
-`dcl-artifacts login`, which opens a browser for the work-email one-time PIN.
-Needs Node 20+, nothing else — no git, no repo access, no `npm install`.
-Re-run the same line to update.
+Same line on macOS, Linux and Windows. It writes the skill — `SKILL.md` and its
+style reference, both shipped inside the npm package — to
+`~/.claude/skills/dcl-artifacts/`, with every command rewritten to
+`npx -y @dcl-regenesislabs/artifacts …`, and then runs `login` unless you are
+already signed in. Run it again to update; it only rewrites what changed.
 
-By hand, with access to this repo (no `npm install` needed; run
-`node cli/artifacts.mjs login` afterwards):
+`login` on its own offers to install the skill afterwards when run in a
+terminal, and stays quiet otherwise. `--skill-dir <dir>` puts the skill
+somewhere else — any agent that reads the `SKILL.md` format, e.g.
+`~/.codex/skills/dcl-artifacts`, or `.claude/skills/dcl-artifacts` inside a
+project to share it with a team.
 
-```bash
-git clone git@github.com:dcl-regenesislabs/ia-generated-artifacts.git ~/.dcl-artifacts
-~/.dcl-artifacts/scripts/install-skill.sh          # or: npm run skill:install, inside the checkout
-```
+Needs Node 20+, nothing else — no git, no repo access, no `npm install`. The
+old `curl … | bash` and `irm … | iex` lines still work: they are stubs that
+run the line above.
 
-The one-line installers leave an existing checkout at `~/.dcl-artifacts` alone,
-so the two ways don't fight.
+Inside this repository, the project-level skill at `.claude/skills/dcl-artifacts/`
+is the source of truth and runs `node cli/artifacts.mjs` directly — `npx` cannot
+resolve a package from inside its own checkout.
 
 ## Signing in
 
@@ -198,8 +188,7 @@ ever pasted anywhere, and the token is never printed.
 | `scripts/smoke.sh` | end-to-end check against a local or deployed host |
 | `scripts/setup-access.mjs` | reconciles the Cloudflare Access apps and policies |
 | `scripts/build-guide.mjs` | regenerates `docs/guide/index.html` from the template assets |
-| `scripts/install.sh`, `scripts/install.ps1` | the one-line installers, served at `/install.sh` and `/install.ps1` |
-| `scripts/build-dist.mjs` | builds `dist/dcl-artifacts.tgz`, served at `/install/dcl-artifacts.tgz` |
+| `scripts/install.sh`, `scripts/install.ps1` | legacy installer stubs served at `/install.sh` and `/install.ps1`; they run `npx … setup` |
 
 R2 layout, per artifact:
 
@@ -248,7 +237,7 @@ path first, which gives these rules:
 | `/_api/*` | bypass | already guarded by the bearer token |
 | `/_health` | bypass | exposes nothing, keeps uptime monitors working |
 | `/p/*` | bypass | opt-in public aliases carry their own secret |
-| `/install.sh`, `/install.ps1`, `/install/*` | bypass | the installers and their tarball; no secrets in any of them |
+| `/install.sh`, `/install.ps1` | bypass | legacy installer stubs; no secrets in them |
 | everything else | allow `@dclregenesislabs.xyz`, `@decentraland.org` | the gate — pages, `/__ui/bar.js`, the in-page API |
 
 Login is Cloudflare's built-in **one-time PIN**: the visitor types their email,
@@ -290,7 +279,7 @@ npx wrangler r2 bucket create dcl-artifacts-preview     # used by `wrangler dev
 npx wrangler kv namespace create TOKENS                 # put the id in wrangler.jsonc
 npx wrangler kv namespace create TOKENS --preview        # and the preview_id
 npx wrangler secret put UPLOAD_TOKEN                     # the shared token, until it is retired
-npm run deploy                                          # builds dist/, provisions the custom domain
+npm run deploy                                          # provisions the custom domain
 
 # Cloudflare Access — needs an API token with Access: Apps and Policies = Edit
 CLOUDFLARE_API_TOKEN=… node scripts/setup-access.mjs --dry-run
@@ -305,8 +294,9 @@ policies to match the table above, so re-run it after any policy change.
 
 ### Releasing the CLI to npm
 
-The package is `cli/`, `shared/` and `templates/` — the `files` list in
-`package.json`; nothing of the Worker ships. Releases go through
+The package is `cli/`, `shared/`, `templates/` and the skill under
+`.claude/skills/dcl-artifacts/` — the `files` list in `package.json`; nothing
+of the Worker ships. Releases go through
 `.github/workflows/publish.yml` using npm **trusted publishing**: npm trusts
 that workflow's GitHub OIDC identity, so there is no npm token in the repo, in
 Actions secrets, or anywhere else, and every release carries provenance.

package/cli/artifacts.mjs

@@ -15,6 +15,7 @@ import { createHash, timingSafeEqual } from "node:crypto";
 import { realpathSync } from "node:fs";
 import { mkdir, open, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
 import { createServer } from "node:http";
+import { createInterface } from "node:readline/promises";
 import { homedir, hostname, userInfo } from "node:os";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -31,6 +32,11 @@ import {
 
 const DEFAULT_BASE = "https://artifacts.dclregenesislabs.xyz";
 const TEMPLATE_DIR = fileURLToPath(new URL("../templates/artifact/", import.meta.url));
+/** The skill as authored. Shipped in the npm package at the same relative path as in the repo. */
+const SKILL_SRC = fileURLToPath(new URL("../.claude/skills/dcl-artifacts/", import.meta.url));
+const PACKAGE = "@dcl-regenesislabs/artifacts";
+/** What the installed skill tells the agent to run. The authored file says `node cli/artifacts.mjs`. */
+const SKILL_COMMAND = `npx -y ${PACKAGE}`;
 const TEMPLATE_TITLE = "Artifact template";
 const MAX_FILE_BYTES = 25 * 1024 * 1024;
 const UPLOAD_CONCURRENCY = 6;
@@ -53,6 +59,7 @@ const MIME = {
 const USAGE = `dcl-artifacts — publish static artifacts to ${DEFAULT_BASE}
 
 Usage
+  dcl-artifacts setup [--skill-dir <dir>]        Install the Claude Code skill and sign in. Run it again to update.
   dcl-artifacts login                            Sign in with your work email, in a browser
   dcl-artifacts logout [--all]                   Revoke this machine's token (--all: every machine)
   dcl-artifacts whoami                           Who the current token belongs to
@@ -74,6 +81,9 @@ Options
                       saved credentials.
   --all               push:   include normally-skipped entries (.git, node_modules, ...)
                       logout: revoke every token issued to your email, not just this one
+  --skill-dir <dir>   Where setup/login put the skill. Default ~/.claude/skills/dcl-artifacts.
+                      Any tool that reads the SKILL.md format works, e.g.
+                      ~/.codex/skills/dcl-artifacts, or .claude/skills/dcl-artifacts in a project.
   --json              Emit machine-readable JSON on stdout
   -h, --help          Show this help
 
@@ -84,19 +94,19 @@ URLs
                                                           the bar at the top of the page, by anyone
                                                           who can open it. Not from here.
 
-Signing in
-  'login' opens a browser, you sign in with a @dclregenesislabs.xyz or
-  @decentraland.org email, and the token it gives back is written to
-  ~/.config/dcl-artifacts/credentials.json (mode 600). Tokens last 90 days;
-  run 'login' again to renew, 'logout' to revoke. Nothing needs to be pasted
-  anywhere, and no token is ever printed.
+Getting started
+  'setup' installs the skill Claude Code uses to publish, then opens a browser
+  where you sign in with a @dclregenesislabs.xyz or @decentraland.org email.
+  The token it gives back is written to ~/.config/dcl-artifacts/credentials.json
+  (mode 600). Tokens last 90 days; run 'login' again to renew, 'logout' to
+  revoke. Nothing needs to be pasted anywhere, and no token is ever printed.
 
 An artifact keeps its id for life; each push with --id adds a version. Pushing
 bytes identical to the latest version records nothing. Blobs are stored by
 digest, so a new version uploads only what changed.`;
 
 function parseArgs(argv) {
-  const opts = { positional: [], name: null, id: null, base: null, token: null, all: false, json: false };
+  const opts = { positional: [], name: null, id: null, base: null, token: null, all: false, json: false, skillDir: null };
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     switch (arg) {
@@ -105,6 +115,7 @@ function parseArgs(argv) {
       case "--base": opts.base = argv[++i]; break;
       case "--token": opts.token = argv[++i]; break;
       case "--all": opts.all = true; break;
+      case "--skill-dir": opts.skillDir = argv[++i]; break;
       case "--json": opts.json = true; break;
       case "-h": case "--help": opts.help = true; break;
       default:
@@ -405,6 +416,69 @@ async function forgetCredentials(base, log) {
   await writeSecret(path, `${JSON.stringify(file, null, 2)}\n`);
 }
 
+// ---------------------------------------------------------------- skill
+
+/**
+ * Where the Claude Code skill goes by default. Any tool that reads the
+ * SKILL.md format can be pointed at instead with --skill-dir.
+ */
+const defaultSkillDir = () => join(homedir(), ".claude", "skills", "dcl-artifacts");
+
+/** The skill files as they should be on disk, with the command rewritten for the package. */
+async function renderSkill() {
+  const skill = (await readFile(join(SKILL_SRC, "SKILL.md"), "utf8")).replaceAll("node cli/artifacts.mjs", SKILL_COMMAND);
+  const style = await readFile(join(SKILL_SRC, "references", "regenesis-artifact-style.md"), "utf8");
+  return { "SKILL.md": skill, "references/regenesis-artifact-style.md": style };
+}
+
+/** True when every file is already there with the same content. */
+async function skillInstalled(dir) {
+  const want = await renderSkill();
+  for (const [rel, body] of Object.entries(want)) {
+    const have = await readFile(join(dir, rel), "utf8").catch(() => null);
+    if (have !== body) return false;
+  }
+  return true;
+}
+
+async function installSkill(dir) {
+  const files = await renderSkill();
+  for (const [rel, body] of Object.entries(files)) {
+    await mkdir(dirname(join(dir, rel)), { recursive: true });
+    await writeFile(join(dir, rel), body);
+  }
+  return Object.keys(files).length;
+}
+
+/**
+ * Yes/no on a real terminal. Anywhere else — CI, a pipe, `curl | bash` — the
+ * answer is no: nothing gets installed that was not explicitly asked for, and
+ * `setup` exists for asking explicitly.
+ */
+async function confirm(question, preferYes) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) return false;
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  try {
+    const answer = (await rl.question(`${question} ${preferYes ? "[Y/n]" : "[y/N]"} `)).trim().toLowerCase();
+    if (!answer) return preferYes;
+    return answer === "y" || answer === "yes";
+  } finally {
+    rl.close();
+  }
+}
+
+/** Is the saved credential, if any, still accepted? */
+async function signedIn(base, log) {
+  const entry = await readCredentials(base, log);
+  if (!entry) return null;
+  try {
+    const me = await new Client(base, entry.token).call("GET", "/_api/whoami");
+    return me?.email ?? null;
+  } catch {
+    return null;
+  }
+}
+
 // ---------------------------------------------------------------- login
 
 const LOGIN_TIMEOUT_MS = 120_000;
@@ -603,6 +677,39 @@ async function main() {
         ? JSON.stringify({ email: res.email, tokenId: res.tokenId, expiresAt: res.expiresAt }, null, 2)
         : `signed in as ${res.email} — expires ${res.expiresAt.slice(0, 10)}`,
     );
+    // The natural next step, offered rather than assumed: `setup` is the
+    // command that does both without asking.
+    const skillDir = opts.skillDir ? resolve(opts.skillDir) : defaultSkillDir();
+    if (!opts.json && !(await skillInstalled(skillDir))) {
+      if (await confirm(`install the Claude Code skill to ${skillDir}?`, true)) {
+        await installSkill(skillDir);
+        log(`skill installed -> ${skillDir}`);
+        log(`in Claude Code, from any project, try:  publish this page as an artifact`);
+      } else {
+        log(`later:  npx -y ${PACKAGE} setup`);
+      }
+    }
+    return;
+  }
+
+  if (command === "setup") {
+    const skillDir = opts.skillDir ? resolve(opts.skillDir) : defaultSkillDir();
+    const fresh = await skillInstalled(skillDir);
+    if (!fresh) await installSkill(skillDir);
+    log(`${fresh ? "skill up to date" : "skill installed"} -> ${skillDir}`);
+
+    let email = await signedIn(base, log);
+    if (email) {
+      log(`already signed in as ${email}`);
+    } else {
+      log("signing you in — a browser window should open");
+      email = (await login(base, log)).email;
+    }
+    console.log(
+      opts.json
+        ? JSON.stringify({ skillDir, email }, null, 2)
+        : `ready — ${email}\nin Claude Code, from any project, try:  publish this page as an artifact`,
+    );
     return;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dcl-regenesislabs/artifacts",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Publish static artifacts to artifacts.dclregenesislabs.xyz — sign in with a work email, push a folder, get a link back",
   "type": "module",
   "bin": {
@@ -9,7 +9,8 @@
   "files": [
     "cli/",
     "shared/",
-    "templates/"
+    "templates/",
+    ".claude/skills/dcl-artifacts/"
   ],
   "engines": {
     "node": ">=20"
@@ -30,11 +31,7 @@
     "typecheck": "tsc --noEmit",
     "push": "node ./cli/artifacts.mjs push",
     "smoke": "./scripts/smoke.sh",
-    "skill:install": "./scripts/install-skill.sh",
-    "guide": "node ./scripts/build-guide.mjs",
-    "dist": "node ./scripts/build-dist.mjs",
-    "predev": "node ./scripts/build-dist.mjs",
-    "predeploy": "node ./scripts/build-dist.mjs"
+    "guide": "node ./scripts/build-guide.mjs"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "^5.20260831.1",