docs: add Brand Kit discovery surfaces

README.md

@@ -2,23 +2,35 @@
 
 Turn a public domain into a deterministic, agent-ready brand context package in one command.
 
-## 10-second demo
+## Package command
 
 ```sh
-npx @replynodes/brand-kit linear.app
-cat brand/brand.json
+npx @replynodes/brand-kit <bare-domain>
 ```
 
 ## Install and run
 
+The published package is scoped as `@replynodes/brand-kit`; the executable remains `brand-kit`.
+
+```sh
+npx @replynodes/brand-kit <bare-domain>
+```
+
+For a source checkout, use this distinct fallback:
+
 ```sh
-npm install -g @replynodes/brand-kit
-brand-kit example.com
+git clone https://github.com/replynodes/brand-kit.git
+cd brand-kit
+npm ci
+node bin/brand-kit.mjs <bare-domain>
 ```
+Pass exactly one bare domain. The client supports Node.js `>=20.19.0`; CI verifies Node 20.x and 22.x, without claiming every OS combination is tested.
 
-The package is scoped as `@replynodes/brand-kit`, while the installed executable remains `brand-kit`.
+## Discovery links
 
-Pass exactly one bare domain. The client supports Node.js `>=20.19.0` on Linux x64/arm64, macOS x64/arm64, and Windows x64. CI verifies Node 20.x and 22.x; that does not claim every OS combination is tested.
+- [Agent skill](SKILL.md)
+- [Machine-readable guidance](llms.txt)
+- [Discovery examples](examples/)
 
 ## Approved use cases
 
@@ -34,16 +46,16 @@ The command creates exactly six files in `./brand/`: `brand.json`, `colors.json`
 
 ## Limitations and non-goals
 
-This is a references-only client: it does not download or decode logos, fonts, or other binaries; scrape pages; follow redirects; sign up; accept API keys; send cookies; make per-capability requests; or provide video, Tailwind, MCP, or telemetry features. Optional source signals can be unavailable. The hosted service remains authoritative for public-address and SSRF checks.
+This is a references-only client: it does not download or decode logos, fonts, or other binaries; scrape pages; follow redirects; sign up; accept API keys; send cookies; make per-capability requests; or provide telemetry features. Optional source signals can be unavailable. The hosted service remains authoritative for public-address and SSRF checks.
 
 ## How it works
 
-The CLI validates one normalized ASCII bare domain, makes one timed HTTPS GET to `https://brand.replynodes.com/{domain}`, normalizes the aggregate response, and writes stable JSON, CSS, and Markdown artifacts. The client uses only Node.js built-ins.
+The CLI validates one normalized ASCII bare domain, makes one timed HTTPS GET to `https://brand.replynodes.com/{bare-domain}`, normalizes the aggregate response, and writes stable JSON, CSS, and Markdown artifacts. The client uses only Node.js built-ins.
 
 ## Attribution and service boundary
 
 The client in this repository is MIT-licensed. The hosted aggregate service at `brand.replynodes.com` is a proprietary ReplyNodes service with its own availability and terms; it is not bundled with, relicensed by, or made open source through this repository. See `NOTICE.md`.
 
 ## Contribution and release notes
 
-See `CONTRIBUTING.md` for checks and contribution boundaries. CI runs smoke/contract checks on Node 20.x and 22.x. The published scoped npm release is `@replynodes/brand-kit@0.1.1`; v0.1.2 is an unpublished patch replacement adding npm discovery keywords.
+See `CONTRIBUTING.md` for checks and contribution boundaries. CI runs smoke/contract checks on Node 20.x and 22.x. The published scoped npm release is `@replynodes/brand-kit@0.1.1`; v0.1.2 is a separate keyword patch.

SKILL.md

@@ -1,16 +1,53 @@
-# @replynodes/brand-kit
+---
+name: brand-kit
+description: Generate and consume a ReplyNodes brand context package for UI, design, content, and handoff work.
+---
 
-Use the public npm package with one bare domain:
+# Brand Kit
+
+## WHEN TO USE
+
+Use this skill when:
+
+- brand context is needed before UI work;
+- a brand kit is requested from a URL or domain;
+- CSS or design tokens are needed;
+- `DESIGN.md` is needed for coding agents;
+- slides, reports, or email need reusable brand references; or
+- logos, colors, fonts, or styleguide signals need to be extracted.
+
+## Contract
+
+Use exactly one bare domain:
 
 ```sh
-npx @replynodes/brand-kit example.com
+npx @replynodes/brand-kit <bare-domain>
 ```
 
-The package is scoped, but its installed executable remains `brand-kit`:
+For a source checkout, use this distinct fallback:
 
 ```sh
-npm install -g @replynodes/brand-kit
-brand-kit example.com
+git clone https://github.com/replynodes/brand-kit.git
+cd brand-kit
+npm ci
+node bin/brand-kit.mjs <bare-domain>
 ```
 
-The client makes one HTTPS GET to `https://brand.replynodes.com/{bare-domain}` and writes the deterministic brand artifacts locally. It requires no API key or signup, does not download binary assets, and does not claim capabilities beyond this service boundary. The v0.1.1 npm publication is the release target and has not yet occurred.
+The client makes one aggregate `GET https://brand.replynodes.com/{bare-domain}` and writes exactly six files in `./brand/`:
+
+- `brand.json`
+- `colors.json`
+- `fonts.json`
+- `logos.json`
+- `tokens.css`
+- `DESIGN.md`
+
+Consume generated `tokens.css` and the JSON/Markdown artifacts in downstream work. Logo, backdrop, font, and other asset values are reference-only URLs or source signals: the client does not download or decode binaries.
+
+Optional source fields can be missing, partial, or unavailable; preserve those semantics rather than inventing values. Empty token output and `Unavailable.` notes are valid results. The client accepts one normalized ASCII bare domain, rejects an existing `./brand` destination, follows no redirects, and uses no credentials, cookies, API keys, scraping, per-capability requests, telemetry, or backend routes.
+
+The service remains authoritative for public-address and SSRF checks. Results reflect available public source signals and are not a guarantee of completeness or freshness.
+
+Canonical repository: https://github.com/replynodes/brand-kit
+
+Canonical guide: https://docs.replynodes.com/docs/guides/brand-kit

examples/brand-reference-package/README.md

@@ -1,12 +1,22 @@
-# Reusable brand reference package for github.com
+# Brand reference package
 
-Prepare local brand references for GitHub slides, reports, or email work:
+Create reusable references for slides, reports, or email from `github.com`.
 
 ```sh
 npx @replynodes/brand-kit github.com
 ```
 
-The package is scoped as `@replynodes/brand-kit`. Version `0.1.1` publication is
-the release target and has not happened. Runtime is one GET to
-`https://brand.replynodes.com/github.com`; no API key or signup is required, and
-no binary downloads are involved.
+For a source checkout, use this distinct fallback:
+
+```sh
+git clone https://github.com/replynodes/brand-kit.git
+cd brand-kit
+npm ci
+node bin/brand-kit.mjs github.com
+```
+
+Expected output in `./brand/`: `brand.json`, `colors.json`, `fonts.json`, `logos.json`, `tokens.css`, and `DESIGN.md`.
+
+Consumer workflow: use `DESIGN.md` for editorial reference, consult the JSON files for structured colors/fonts/logo references, and use `tokens.css` when a web export needs the same available tokens.
+
+Limitations: logo, backdrop, and font values are reference-only; no binaries are downloaded or decoded. The request is one aggregate GET with no credentials, and fields can be missing, partial, or unavailable.

examples/build-landing-page-with-agent/README.md

@@ -1,13 +1,22 @@
-# Build a landing page with an agent for vercel.com
+# Build a landing page with an agent
 
-Give an agent a local, deterministic brand reference package for a Vercel
-landing page:
+Use `vercel.com` to gather brand context before implementing a landing page.
 
 ```sh
 npx @replynodes/brand-kit vercel.com
 ```
 
-The package is scoped as `@replynodes/brand-kit`. Version `0.1.1` publication is
-the release target and has not happened. Runtime is one GET to
-`https://brand.replynodes.com/vercel.com`; no API key or signup is required, and
-no binary downloads are involved.
+For a source checkout, use this distinct fallback:
+
+```sh
+git clone https://github.com/replynodes/brand-kit.git
+cd brand-kit
+npm ci
+node bin/brand-kit.mjs vercel.com
+```
+
+Expected output in `./brand/`: `brand.json`, `colors.json`, `fonts.json`, `logos.json`, `tokens.css`, and `DESIGN.md`.
+
+Consumer workflow: read `DESIGN.md` and the JSON context before UI work, use `tokens.css` for available colors and fonts, and treat logo URLs as references when selecting imagery.
+
+Limitations: the client performs one aggregate GET, uses no credentials, does not fetch or decode asset binaries, and source fields may be missing, partial, or unavailable. An existing `./brand` directory is rejected.

examples/css-token-handoff/README.md

@@ -1,12 +1,22 @@
-# CSS and token handoff for stripe.com
+# CSS token handoff
 
-Generate local CSS and design-token references for a Stripe handoff:
+Prepare a token handoff for `stripe.com`.
 
 ```sh
 npx @replynodes/brand-kit stripe.com
 ```
 
-The package is scoped as `@replynodes/brand-kit`. Version `0.1.1` publication is
-the release target and has not happened. Runtime is one GET to
-`https://brand.replynodes.com/stripe.com`; no API key or signup is required, and
-no binary downloads are involved.
+For a source checkout, use this distinct fallback:
+
+```sh
+git clone https://github.com/replynodes/brand-kit.git
+cd brand-kit
+npm ci
+node bin/brand-kit.mjs stripe.com
+```
+
+Expected output in `./brand/`: `brand.json`, `colors.json`, `fonts.json`, `logos.json`, `tokens.css`, and `DESIGN.md`.
+
+Consumer workflow: consume the generated `tokens.css` in the stylesheet or map its variables into the project’s existing token system; use the JSON files to inspect provenance.
+
+Limitations: tokens only reflect available source signals, so missing, partial, or unavailable colors and fonts remain possible. The client makes one aggregate GET, uses no credentials, and does not fetch asset binaries.

examples/design-handoff-audit/README.md

@@ -1,12 +1,22 @@
-# Design handoff audit for notion.so
+# Design handoff audit
 
-Create a portable set of brand references for auditing a Notion design handoff:
+Audit available design signals for `notion.so`.
 
 ```sh
 npx @replynodes/brand-kit notion.so
 ```
 
-The package is scoped as `@replynodes/brand-kit`. Version `0.1.1` publication is
-the release target and has not happened. Runtime is one GET to
-`https://brand.replynodes.com/notion.so`; no API key or signup is required, and
-no binary downloads are involved.
+For a source checkout, use this distinct fallback:
+
+```sh
+git clone https://github.com/replynodes/brand-kit.git
+cd brand-kit
+npm ci
+node bin/brand-kit.mjs notion.so
+```
+
+Expected output in `./brand/`: `brand.json`, `colors.json`, `fonts.json`, `logos.json`, `tokens.css`, and `DESIGN.md`.
+
+Consumer workflow: compare `DESIGN.md` with the JSON source fields, review `tokens.css` for usable variables, and record unavailable signals as gaps in the handoff rather than filling them in.
+
+Limitations: the client makes one aggregate GET, uses no credentials, does not scrape or fetch binaries, and can return missing, partial, or unavailable source signals. An existing `./brand` destination is rejected.

examples/generate-brand-kit/README.md

@@ -1,12 +1,22 @@
-# Generate a brand kit for linear.app
+# Generate a brand kit
 
-Create an agent-ready local brand context package from Linear’s public domain:
+Generate a reference package for `linear.app`.
 
 ```sh
 npx @replynodes/brand-kit linear.app
 ```
 
-The package is scoped as `@replynodes/brand-kit`. Version `0.1.1` publication is
-the release target and has not happened. At runtime, the client makes one GET to
-`https://brand.replynodes.com/linear.app`; no API key or signup is required, and
-no binary downloads are involved.
+For a source checkout, use this distinct fallback:
+
+```sh
+git clone https://github.com/replynodes/brand-kit.git
+cd brand-kit
+npm ci
+node bin/brand-kit.mjs linear.app
+```
+
+Expected output in `./brand/`: `brand.json`, `colors.json`, `fonts.json`, `logos.json`, `tokens.css`, and `DESIGN.md`.
+
+Consumer workflow: inspect the six artifacts as a single package, use structured JSON for automation, and use `DESIGN.md` for a readable summary and provenance.
+
+Limitations: one aggregate GET is made to the hosted service; no credentials, scraping, redirects, or asset downloads are used. Values can be missing, partial, or unavailable, and an existing `./brand` destination is rejected.

llms.txt

@@ -1,5 +1,40 @@
-# @replynodes/brand-kit
+# brand-kit
 
-Run `npx @replynodes/brand-kit <bare-domain>` with exactly one bare domain. A global install uses `npm install -g @replynodes/brand-kit`, then the executable is `brand-kit <bare-domain>`.
+## WHEN TO USE
 
-The client makes one HTTPS GET to `https://brand.replynodes.com/{bare-domain}` and writes local brand references and design artifacts. It requires no API key or signup and does not download binary assets. The v0.1.1 npm publication is the release target; the package is intended to be public on npm but is not yet published.
+- brand context before UI work
+- brand kit from a URL/domain
+- CSS/design-token handoff by consuming generated tokens
+- DESIGN.md guidance for coding agents
+- slides, reports, email, or logo/color/font/styleguide reference extraction
+
+## INSTALL / USAGE
+
+- package_command: `npx @replynodes/brand-kit <bare-domain>`
+- source_fallback: `git clone https://github.com/replynodes/brand-kit.git && cd brand-kit && npm ci && node bin/brand-kit.mjs <bare-domain>`
+- request: one aggregate `GET https://brand.replynodes.com/{bare-domain}`
+
+## SIX OUTPUTS
+
+- `brand/brand.json`
+- `brand/colors.json`
+- `brand/fonts.json`
+- `brand/logos.json`
+- `brand/tokens.css`
+- `brand/DESIGN.md`
+
+## CONTRACT / LIMITATIONS
+
+- input: exactly one normalized ASCII bare domain
+- assets: logo, backdrop, font, and other asset values are reference-only; binaries are not fetched or decoded
+- data: fields may be missing, partial, or unavailable; do not invent values
+- no_credentials: true
+- no_redirects: true
+- no_scraping: true
+- no_per_capability_requests: true
+- destination: existing `./brand` is rejected
+
+## CANONICAL LINKS
+
+- repository: https://github.com/replynodes/brand-kit
+- guide: https://docs.replynodes.com/docs/guides/brand-kit