panelize 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -4,6 +4,26 @@ All notable changes to Panelize are listed here. The format follows [Keep a Chan
 
 ## [Unreleased]
 
+## [0.1.2] - 2026-10-12
+
+No change to the components, props, or theme.
+
+### Added
+
+- `npx panelize init-agents` adds a Panelize section to a project’s `AGENTS.md` so coding agents read `llms.txt` and `docs/composition.md`. It never overwrites existing content and re-running updates only its own section. `--cursor`, `--claude`, `--copilot`, and `--all` write tool-specific files; `--dry-run` previews.
+
+### Changed
+
+- `examples/AGENTS.md` is now a `##` section meant to be merged into an existing `AGENTS.md`.
+- `examples/cursor-rule.mdc` no longer sets `alwaysApply: true`. The agent pulls it in when the task is building or editing UI.
+- README and `llms.txt` lead with the agent setup step; links to maintainer files in `llms.txt` now point at GitHub.
+
+## [0.1.1] - 2026-10-12
+
+### Changed
+
+- Releases are published through npm trusted publishing with staged releases. No library code changed.
+
 ## [0.1.0] - 2026-10-11
 
 First public release.
@@ -26,5 +46,7 @@ First public release.
 - The library does not load font files and has no scheme toggle. The host owns both.
 - Next.js App Router needs the styled-components registry (see the README).
 
-[Unreleased]: https://github.com/jayzizzle/panelize/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/jayzizzle/panelize/compare/v0.1.2...HEAD
+[0.1.2]: https://github.com/jayzizzle/panelize/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/jayzizzle/panelize/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/jayzizzle/panelize/releases/tag/v0.1.0

package/README.md

@@ -48,6 +48,26 @@ export function App() {
 
 With no `theme` prop the provider uses `defaultTheme`. To set colors, brand, and type, see [Theme](#theme).
 
+## Using an AI agent?
+
+Panelize ships docs written for coding agents (`llms.txt` and `docs/`). Installing the package puts them in `node_modules`, but agents do not look there on their own. Point them at it once, from your project root:
+
+```sh
+npx panelize init-agents
+```
+
+This adds a short Panelize section to `AGENTS.md`, a file most coding agents read. The section tells the agent to read `node_modules/panelize/llms.txt` and `docs/composition.md` before writing UI, so it stays current when you upgrade the package. If `AGENTS.md` already exists, your content is left alone and only the section between the `<!-- panelize:start -->` and `<!-- panelize:end -->` lines is added or updated. Commit the result.
+
+| Option      | Also writes                                                                                                                             |
+| ----------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `--cursor`  | `.cursor/rules/panelize.mdc`, pulled in by the agent when the task is building or editing UI (`--force` overwrites a file that differs) |
+| `--claude`  | `CLAUDE.md` containing an `@AGENTS.md` import, for Claude Code                                                                          |
+| `--copilot` | `.github/copilot-instructions.md`                                                                                                       |
+| `--all`     | all of the above                                                                                                                        |
+| `--dry-run` | Writes nothing; prints what would change                                                                                                |
+
+Prefer to do it by hand, or use a tool with no instructions file? Paste the section from [`examples/AGENTS.md`](examples/AGENTS.md) into its instructions or system prompt.
+
 ## Next.js (App Router)
 
 Panelize is client UI with `'use client'` in the bundle, so you can import it from Server Components. styled-components needs its official registry, or server-rendered pages arrive **unstyled** and flash on hydrate.
@@ -167,10 +187,7 @@ Evergreen browsers: **Chrome / Edge 119+, Safari 16.5+, Firefox 121+**. The floo
 
 **Using Panelize in an app:** read [`llms.txt`](llms.txt) then [`docs/composition.md`](docs/composition.md). After `npm install panelize`, those files are `node_modules/panelize/llms.txt` (export `panelize/llms.txt`) and `node_modules/panelize/docs/`. One-file dump: `llms-full.txt`.
 
-Copy a ready-made rule into the **host** app:
-
-- Cursor: `node_modules/panelize/examples/cursor-rule.mdc` → `.cursor/rules/panelize.mdc` (`alwaysApply: true`).
-- Any agent (`AGENTS.md`, Copilot instructions, and so on): `node_modules/panelize/examples/AGENTS.md`.
+Set up the **host** project with `npx panelize init-agents` (see [Using an AI agent?](#using-an-ai-agent)). The drop-in files are `node_modules/panelize/examples/AGENTS.md` and `examples/cursor-rule.mdc`.
 
 Copyable layouts (page, sidebar, centered card, form, dashboard grid): [`docs/recipes.md`](docs/recipes.md). One line per export: [`docs/components.md`](docs/components.md).
 

package/bin/panelize.mjs

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const packageRoot = join(dirname(fileURLToPath(import.meta.url)), '..')
+const START = '<!-- panelize:start -->'
+const END = '<!-- panelize:end -->'
+
+const USAGE = `Usage: panelize init-agents [options]
+
+Adds Panelize agent instructions to the project in the current directory.
+Run it from your project root (the folder with package.json).
+
+By default it writes a Panelize section into AGENTS.md. Existing content outside
+the section is never touched, and re-running updates only the section.
+
+Options:
+  --cursor    also write .cursor/rules/panelize.mdc
+  --claude    also write CLAUDE.md (imports AGENTS.md)
+  --copilot   also write .github/copilot-instructions.md
+  --all       --cursor --claude --copilot
+  --force     overwrite an existing .cursor/rules/panelize.mdc that differs
+  --dry-run   print what would change and write nothing
+  --help      show this message
+`
+
+const flags = new Set(['--cursor', '--claude', '--copilot', '--all', '--force', '--dry-run'])
+
+function fail(message) {
+  console.error(message)
+  process.exit(1)
+}
+
+const [command, ...args] = process.argv.slice(2)
+if (!command || command === '--help' || command === '-h' || args.includes('--help')) {
+  console.log(USAGE)
+  process.exit(command ? 0 : 1)
+}
+if (command !== 'init-agents') fail(`Unknown command "${command}".\n\n${USAGE}`)
+const unknown = args.find((arg) => !flags.has(arg))
+if (unknown) fail(`Unknown option "${unknown}".\n\n${USAGE}`)
+
+const has = (flag) => args.includes(flag)
+const all = has('--all')
+const dryRun = has('--dry-run')
+const cwd = process.cwd()
+if (!existsSync(join(cwd, 'package.json'))) {
+  fail('No package.json in this directory. Run this from your project root.')
+}
+
+const read = (path) => readFileSync(path, 'utf8')
+const packaged = (file) => read(join(packageRoot, file))
+
+function write(path, text) {
+  if (dryRun) return
+  mkdirSync(dirname(path), { recursive: true })
+  writeFileSync(path, text)
+}
+
+// Insert or replace the marked Panelize section in a Markdown file.
+function mergeSection(file, body) {
+  const path = join(cwd, file)
+  const section = `${START}\n${body.trim()}\n${END}\n`
+  if (!existsSync(path)) {
+    write(path, section)
+    return 'created'
+  }
+  const current = read(path)
+  const eol = current.includes('\r\n') ? '\r\n' : '\n'
+  const text = section.replace(/\n/g, eol)
+  const start = current.indexOf(START)
+  const end = current.indexOf(END)
+  if (start === -1 && end === -1) {
+    write(path, current.trim() ? `${current.trimEnd()}${eol}${eol}${text}` : text)
+    return 'appended'
+  }
+  if (start === -1 || end < start) {
+    throw new Error(`${file} has a damaged Panelize section (check the ${START} / ${END} lines)`)
+  }
+  const tail = current.slice(end + END.length).replace(/^\r?\n/, '')
+  const next = current.slice(0, start) + text + tail
+  if (next === current) return 'unchanged'
+  write(path, next)
+  return 'updated'
+}
+
+// Write a whole file. A different existing file is left alone unless --force.
+function writeWhole(file, body) {
+  const path = join(cwd, file)
+  if (!existsSync(path)) {
+    write(path, body)
+    return 'created'
+  }
+  if (read(path) === body) return 'unchanged'
+  if (!has('--force')) return 'skipped (exists and differs; use --force to overwrite)'
+  write(path, body)
+  return 'overwritten'
+}
+
+const agents = packaged('examples/AGENTS.md')
+const steps = [['AGENTS.md', () => mergeSection('AGENTS.md', agents)]]
+if (all || has('--cursor')) {
+  const rule = () => writeWhole('.cursor/rules/panelize.mdc', packaged('examples/cursor-rule.mdc'))
+  steps.push(['.cursor/rules/panelize.mdc', rule])
+}
+if (all || has('--claude')) steps.push(['CLAUDE.md', () => mergeSection('CLAUDE.md', '@AGENTS.md')])
+if (all || has('--copilot')) {
+  steps.push([
+    '.github/copilot-instructions.md',
+    () => mergeSection('.github/copilot-instructions.md', agents),
+  ])
+}
+
+let failed = false
+for (const [file, run] of steps) {
+  try {
+    console.log(`${run()}  ${file}${dryRun ? '  (dry run)' : ''}`)
+  } catch (error) {
+    failed = true
+    console.error(`error    ${file}: ${error.message}`)
+  }
+}
+if (!failed && !dryRun) console.log('\nCommit these files so everyone on the project gets them.')
+process.exit(failed ? 1 : 0)

package/examples/AGENTS.md

@@ -1,4 +1,4 @@
-# Agent notes (UI)
+## Panelize (UI)
 
 This app builds views with [Panelize](https://github.com/jayzizzle/panelize).
 

package/examples/cursor-rule.mdc

@@ -1,6 +1,6 @@
 ---
-description: Compose views with Panelize layout primitives and type
-alwaysApply: true
+description: Build and edit frontend UI (pages, views, layouts, components) in a project that has panelize installed, including new files that do not import it yet. Compose with Panelize layout primitives and type.
+alwaysApply: false
 ---
 
 # Panelize (this app)

package/llms-full.txt

@@ -4,7 +4,9 @@
 
 > A React layout kit. Named boxes and type are the map of the screen. `createPanelizeTheme` + `PanelizeProvider` + `usePanelizeTheme` standardize paint. Forms are bonus.
 
-This file is for agents **building apps and custom components with Panelize**. Maintainers of this repo: [CONTRIBUTING.md](CONTRIBUTING.md) and [AGENTS.md](AGENTS.md). After `npm install panelize`, read `node_modules/panelize/llms.txt` (or the package export `panelize/llms.txt`). One-file dump: [llms-full.txt](llms-full.txt).
+This file is for agents **building apps and custom components with Panelize**. Maintainers of this repo: [CONTRIBUTING.md](https://github.com/jayzizzle/panelize/blob/main/CONTRIBUTING.md) and [AGENTS.md](https://github.com/jayzizzle/panelize/blob/main/AGENTS.md). After `npm install panelize`, read `node_modules/panelize/llms.txt` (or the package export `panelize/llms.txt`). One-file dump: [llms-full.txt](llms-full.txt).
+
+**Humans:** if you are setting up a project for an agent, run `npx panelize init-agents` from the project root. It adds a Panelize section to `AGENTS.md` that points agents here. See [Host setup](#host-setup).
 
 Import from `'panelize'`. Wrap the host once with `PanelizeProvider`. Do not take over the host’s styled-components `ThemeProvider`. Do not set `html` / `body` from the library. Host CSS must give the shell a height (`html`, `body`, `#root { height: 100% }` for a filled app).
 
@@ -42,10 +44,11 @@ The library does not warn at runtime if a host ignores this. Follow it anyway
 
 - [llms-full.txt](llms-full.txt): this index, every `docs/` page, and the theme keys in one file
 
-## Host setup files
+## Host setup
+
+Agents only know about these docs if the host project points at them. From the project root, `npx panelize init-agents` adds a marked Panelize section to `AGENTS.md` (created if missing, otherwise appended; re-running updates only that section). Add `--cursor`, `--claude`, `--copilot`, or `--all` for tool-specific files, and `--dry-run` to preview.
 
-- [examples/cursor-rule.mdc](examples/cursor-rule.mdc): drop into a host app’s `.cursor/rules/`
-- [examples/AGENTS.md](examples/AGENTS.md): drop into a host app’s `AGENTS.md`
+By hand, copy the section from [examples/AGENTS.md](examples/AGENTS.md) into the host’s agent instructions (`AGENTS.md`, `CLAUDE.md`, Copilot instructions, or a system prompt). Cursor users can also copy [examples/cursor-rule.mdc](examples/cursor-rule.mdc) to `.cursor/rules/panelize.mdc`.
 
 ## Human docs
 

package/llms.txt

@@ -2,7 +2,9 @@
 
 > A React layout kit. Named boxes and type are the map of the screen. `createPanelizeTheme` + `PanelizeProvider` + `usePanelizeTheme` standardize paint. Forms are bonus.
 
-This file is for agents **building apps and custom components with Panelize**. Maintainers of this repo: [CONTRIBUTING.md](CONTRIBUTING.md) and [AGENTS.md](AGENTS.md). After `npm install panelize`, read `node_modules/panelize/llms.txt` (or the package export `panelize/llms.txt`). One-file dump: [llms-full.txt](llms-full.txt).
+This file is for agents **building apps and custom components with Panelize**. Maintainers of this repo: [CONTRIBUTING.md](https://github.com/jayzizzle/panelize/blob/main/CONTRIBUTING.md) and [AGENTS.md](https://github.com/jayzizzle/panelize/blob/main/AGENTS.md). After `npm install panelize`, read `node_modules/panelize/llms.txt` (or the package export `panelize/llms.txt`). One-file dump: [llms-full.txt](llms-full.txt).
+
+**Humans:** if you are setting up a project for an agent, run `npx panelize init-agents` from the project root. It adds a Panelize section to `AGENTS.md` that points agents here. See [Host setup](#host-setup).
 
 Import from `'panelize'`. Wrap the host once with `PanelizeProvider`. Do not take over the host’s styled-components `ThemeProvider`. Do not set `html` / `body` from the library. Host CSS must give the shell a height (`html`, `body`, `#root { height: 100% }` for a filled app).
 
@@ -40,10 +42,11 @@ The library does not warn at runtime if a host ignores this. Follow it anyway
 
 - [llms-full.txt](llms-full.txt): this index, every `docs/` page, and the theme keys in one file
 
-## Host setup files
+## Host setup
+
+Agents only know about these docs if the host project points at them. From the project root, `npx panelize init-agents` adds a marked Panelize section to `AGENTS.md` (created if missing, otherwise appended; re-running updates only that section). Add `--cursor`, `--claude`, `--copilot`, or `--all` for tool-specific files, and `--dry-run` to preview.
 
-- [examples/cursor-rule.mdc](examples/cursor-rule.mdc): drop into a host app’s `.cursor/rules/`
-- [examples/AGENTS.md](examples/AGENTS.md): drop into a host app’s `AGENTS.md`
+By hand, copy the section from [examples/AGENTS.md](examples/AGENTS.md) into the host’s agent instructions (`AGENTS.md`, `CLAUDE.md`, Copilot instructions, or a system prompt). Cursor users can also copy [examples/cursor-rule.mdc](examples/cursor-rule.mdc) to `.cursor/rules/panelize.mdc`.
 
 ## Human docs
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "panelize",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "A React layout kit: named panels, tracks, grid, and type, themed with createPanelizeTheme and PanelizeProvider.",
   "keywords": [
     "react",
@@ -23,6 +23,9 @@
   "author": "Jon Zamora",
   "type": "module",
   "sideEffects": false,
+  "bin": {
+    "panelize": "./bin/panelize.mjs"
+  },
   "main": "./dist/panelize.cjs",
   "module": "./dist/panelize.es.js",
   "types": "./dist/index.d.ts",
@@ -44,6 +47,7 @@
     "./package.json": "./package.json"
   },
   "files": [
+    "bin",
     "dist",
     "llms.txt",
     "llms-full.txt",