From ae6ff34f23adb3d0ba950f044cb8d5b8578bbb74 Mon Sep 17 00:00:00 2001 From: replynodes Date: Mon, 28 Sep 2026 16:51:18 +0200 Subject: [PATCH 1/2] docs: add brand kit discovery surfaces --- README.md | 23 ++++++-- SKILL.md | 53 +++++++++++++++++++ examples/brand-reference-package/README.md | 22 ++++++++ .../build-landing-page-with-agent/README.md | 22 ++++++++ examples/css-token-handoff/README.md | 22 ++++++++ examples/design-handoff-audit/README.md | 22 ++++++++ examples/generate-brand-kit/README.md | 22 ++++++++ llms.txt | 42 +++++++++++++++ 8 files changed, 223 insertions(+), 5 deletions(-) create mode 100644 SKILL.md create mode 100644 examples/brand-reference-package/README.md create mode 100644 examples/build-landing-page-with-agent/README.md create mode 100644 examples/css-token-handoff/README.md create mode 100644 examples/design-handoff-audit/README.md create mode 100644 examples/generate-brand-kit/README.md create mode 100644 llms.txt diff --git a/README.md b/README.md index 8fb5ccb..9b691aa 100644 --- a/README.md +++ b/README.md @@ -2,24 +2,37 @@ Turn a public domain into a deterministic, agent-ready brand context package in one command. -## 10-second demo +## Intended package command + +Npm publication is currently unavailable/E404 pending #561; this is the intended command once the package is published: ```sh npx brand-kit linear.app -cat brand/brand.json ``` ## Install and run +Npm publication is currently unavailable/E404 pending #561. The truthful source/clone path is: + ```sh -npm install -g 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 example.com ``` -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. +The intended package command is exactly `npx brand-kit `, but clean npm use is pending #561. 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. + +## Discovery links + +- [Agent skill](SKILL.md) +- [Machine-readable guidance](llms.txt) +- [Discovery examples](examples/) ## Approved use cases +These are the approved launch-story command forms; the npm path remains pending #561. + - Agent-ready brand context: `npx brand-kit linear.app` - On-brand landing-page bootstrap: `npx brand-kit vercel.com` - CSS/token handoff: `npx brand-kit stripe.com` diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..c6c43c7 --- /dev/null +++ b/SKILL.md @@ -0,0 +1,53 @@ +--- +name: brand-kit +description: Generate and consume a ReplyNodes brand context package for UI, design, content, and handoff work. +--- + +# 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, design tokens, or a Tailwind handoff is needed (consume generated tokens; never add a CLI Tailwind flag); +- `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 + +The intended command is exactly: + +```sh +npx brand-kit +``` + +Npm publication is currently unavailable/E404 and pending #561. Do not claim that `npx` or `npm install` works now. Use the truthful source path: + +```sh +git clone https://github.com/replynodes/brand-kit.git +cd brand-kit +npm ci +node bin/brand-kit.mjs +``` + +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. There is no CLI Tailwind flag. 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, video, MCP, 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 diff --git a/examples/brand-reference-package/README.md b/examples/brand-reference-package/README.md new file mode 100644 index 0000000..4486eaf --- /dev/null +++ b/examples/brand-reference-package/README.md @@ -0,0 +1,22 @@ +# Brand reference package + +Create reusable references for slides, reports, or email from `github.com`. + +```sh +npx brand-kit github.com +``` + +The intended npm command is shown above, but clean npm use is blocked until #561 publishes the package. The truthful source invocation is: + +```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. diff --git a/examples/build-landing-page-with-agent/README.md b/examples/build-landing-page-with-agent/README.md new file mode 100644 index 0000000..4b933dc --- /dev/null +++ b/examples/build-landing-page-with-agent/README.md @@ -0,0 +1,22 @@ +# Build a landing page with an agent + +Use `vercel.com` to gather brand context before implementing a landing page. + +```sh +npx brand-kit vercel.com +``` + +The intended npm command is shown above, but clean npm use is blocked until #561 publishes the package. The truthful source invocation is: + +```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. diff --git a/examples/css-token-handoff/README.md b/examples/css-token-handoff/README.md new file mode 100644 index 0000000..6023c04 --- /dev/null +++ b/examples/css-token-handoff/README.md @@ -0,0 +1,22 @@ +# CSS token handoff + +Prepare a token handoff for `stripe.com`. + +```sh +npx brand-kit stripe.com +``` + +The intended npm command is shown above, but clean npm use is blocked until #561 publishes the package. The truthful source invocation is: + +```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. Do not add a CLI Tailwind flag. + +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. diff --git a/examples/design-handoff-audit/README.md b/examples/design-handoff-audit/README.md new file mode 100644 index 0000000..05e47de --- /dev/null +++ b/examples/design-handoff-audit/README.md @@ -0,0 +1,22 @@ +# Design handoff audit + +Audit available design signals for `notion.so`. + +```sh +npx brand-kit notion.so +``` + +The intended npm command is shown above, but clean npm use is blocked until #561 publishes the package. The truthful source invocation is: + +```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. diff --git a/examples/generate-brand-kit/README.md b/examples/generate-brand-kit/README.md new file mode 100644 index 0000000..c087a65 --- /dev/null +++ b/examples/generate-brand-kit/README.md @@ -0,0 +1,22 @@ +# Generate a brand kit + +Generate a reference package for `linear.app`. + +```sh +npx brand-kit linear.app +``` + +The intended npm command is shown above, but clean npm use is blocked until #561 publishes the package. The truthful source invocation is: + +```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. diff --git a/llms.txt b/llms.txt new file mode 100644 index 0000000..e589a16 --- /dev/null +++ b/llms.txt @@ -0,0 +1,42 @@ +# brand-kit + +## WHEN TO USE + +- 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 + +- intended_command: `npx brand-kit ` +- npm_status: unavailable/E404; pending #561 +- source_invocation: `git clone https://github.com/replynodes/brand-kit.git && cd brand-kit && npm ci && node bin/brand-kit.mjs ` +- 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 +- no_cli_tailwind_flag: true; consume generated `tokens.css` +- destination: existing `./brand` is rejected + +## CANONICAL LINKS + +- repository: https://github.com/replynodes/brand-kit +- guide: https://docs.replynodes.com/docs/guides/brand-kit From 60d64112ae419e781c843a3146f2b075f318f61e Mon Sep 17 00:00:00 2001 From: replynodes Date: Tue, 29 Sep 2026 02:48:36 +0200 Subject: [PATCH 2/2] docs: correct brand kit discovery guidance --- README.md | 4 ++-- SKILL.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 295d2fe..c296cf2 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ Turn a public domain into a deterministic, agent-ready brand context package in ## Package command ```sh -npx @replynodes/brand-kit linear.app +npx @replynodes/brand-kit ``` ## Install and run @@ -46,7 +46,7 @@ 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 diff --git a/SKILL.md b/SKILL.md index c868ff4..c5287d2 100644 --- a/SKILL.md +++ b/SKILL.md @@ -44,7 +44,7 @@ The client makes one aggregate `GET https://brand.replynodes.com/{bare-domain}` 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, video, MCP, or backend routes. +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.