@ariestools/cli 0.1.6

package/dist/plugins/xy-readme/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "xy-readme",
+  "version": "0.1.0",
+  "description": "Author, audit, and bootstrap package READMEs in the xylabs / xyo convention"
+}

package/dist/plugins/xy-readme/skills/readme-audit/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: readme-audit
+description: Audit a package README against the xylabs / xyo convention. Reports missing or out-of-order sections, malformed badges, wrong license link style, missing reference-link definitions, and other deviations. Use when the user asks to "lint", "audit", "check", "review", or "validate" a README in a xylabs/ or XYOracleNetwork/ repo.
+---
+
+# README Audit (xylabs / xyo convention)
+
+This skill audits an existing `README.md` against the convention codified in
+the `readme-author` skill. It is read-only by default — produce a report,
+then ask the user before making fixes. If the user explicitly asked to
+"fix", apply changes after the audit.
+
+## When to use
+
+- User says "audit", "lint", "check", "review", "validate" + README.
+- Before publishing a new package.
+- During a sweep to bring multiple packages into alignment.
+
+## Audit checklist
+
+Walk through every check in order. For each, emit a line beginning with
+`✓` (pass), `✗` (fail), or `⚠` (warning / optional). Group by section.
+
+### 1. Header
+
+- ✓/✗ First non-blank line is `[![logo][]][logo-link]`.
+- ✓/✗ Title is a single `# {{name}}` line where `{{name}}` matches
+  `package.json#name` exactly (including `@scope/`).
+- ✓/✗ Two badge lines follow the title:
+  `[![npm-badge][]][npm-link]` and `[![license-badge][]][license-link]`.
+- ✓/✗ Tagline is a single `> ` line directly after the badges.
+
+### 2. Section presence and order
+
+The required-and-optional section order:
+
+1. (Header — checked above)
+2. Table of Contents *(aggregate only)*
+3. About *or* Description (aggregate uses "Description")
+4. Install
+5. Subpath Exports *(when applicable)*
+6. What's Inside
+7. Peer Dependencies *(when applicable)*
+8. Building Locally
+9. Maintainers
+10. License
+11. Credits
+12. Reference link definitions (footer)
+
+Required for all packages: Install, What's Inside, Building Locally,
+Maintainers, License, Credits, Reference link definitions.
+
+- ✓/✗ Required sections all present.
+- ✓/✗ Sections appear in the order above (skip-allowed for optional ones).
+- ✗ Flag any section that uses a different name (e.g. `## Setup` instead of
+  `## Install`, `## Authors` instead of `## Maintainers`).
+
+### 3. Install section
+
+- ✓/✗ Contains exactly four `Using <pm>:` blocks in this order: npm, yarn,
+  pnpm, bun.
+- ✓/✗ Each block uses ` ```sh ` as the language.
+- ✓/✗ The install commands are:
+  - `npm i --save {{NAME}}`
+  - `yarn add {{NAME}}`
+  - `pnpm add {{NAME}}`
+  - `bun add {{NAME}}`
+
+### 4. Building Locally
+
+- ✓/✗ Contains a single `sh` code block with three lines:
+  - `xy build {{NAME}}`
+  - `xy test {{NAME}}`
+  - `xy lint {{NAME}}`
+- ✗ Bare `xy build` (unscoped) is incorrect for a *package* README. It is
+  acceptable in the aggregate-tier *root* README only, and only when followed
+  by an explicit "Scope to this package" sentence.
+
+### 5. Maintainers
+
+- ✓/✗ Section present and is an HTML `<table>` (do NOT enforce who is in it
+  or any specific layout — the table is human-managed).
+- ⚠ If the section is missing, that's a fail; suggest copying the standard
+  table from the `readme-author` skill.
+
+### 6. License
+
+- ✓/✗ Section text is `See the [LICENSE](./LICENSE) file (LGPL-3.0-only).`
+  *or* the longer aggregate-root variant. Either is acceptable.
+- ✗ Absolute LICENSE links (e.g. `https://github.com/.../LICENSE`) are
+  incorrect for package READMEs — must be the relative `./LICENSE`.
+
+### 7. Credits
+
+- ✓/✗ Exactly: `[Made with 🔥 and ❄️ by XYO](https://xyo.network)`.
+
+### 8. Reference link definitions
+
+The file MUST end with these definitions (in this order, blank lines between
+each pair):
+
+```text
+[logo]: https://cdn.xy.company/img/brand/XYO_full_colored.png
+[logo-link]: https://xyo.network
+
+[npm-badge]: https://img.shields.io/npm/v/{{NAME}}.svg
+[npm-link]: https://www.npmjs.com/package/{{NAME}}
+
+[license-badge]: https://img.shields.io/npm/l/{{NAME}}.svg
+[license-link]: ./LICENSE
+```
+
+- ✓/✗ All six definitions present.
+- ✓/✗ Each `{{NAME}}` matches `package.json#name`.
+- ✓/✗ `[license-link]` is `./LICENSE` (relative, not absolute).
+- ✓/✗ `[logo]` URL is `https://cdn.xy.company/img/brand/XYO_full_colored.png`.
+- ✗ Flag any definition that points at `xylabs.com` instead of `xyo.network`
+  for `[logo-link]` (older template variant).
+
+### 9. Cross-checks
+
+- ✓/✗ Every reference-style link used inline (`[foo][]` or `[bar][baz]`) has
+  a definition in the footer.
+- ✓/✗ No unused reference-link definitions.
+- ✓/✗ Exactly one `# H1` (the title). All other headings are `##` or deeper.
+
+## Tier-specific checks
+
+After the universal checks, identify the tier (using package-tier heuristics
+from the `readme-author` skill) and run these:
+
+### Aggregate
+
+- ✓/✗ Has `## Table of Contents`.
+- ✓/✗ Uses `## Description` (not `## About`).
+- ✓/✗ Description prose links to component packages by full npm URL.
+
+### Mid-tier
+
+- ⚠ If the package has more than one entry in `exports`, expect a
+  `## Subpath Exports` section.
+
+### Leaf
+
+- ⚠ Leaf packages may omit Peer Dependencies; flag only if `peerDependencies`
+  in `package.json` is non-trivial and the section is missing.
+
+## Output format
+
+Produce a markdown report shaped like this:
+
+```markdown
+# README audit: `{{NAME}}` ({{tier}})
+
+## Header
+✓ Logo line
+✓ Title matches package.json
+✗ Tagline missing — add a `> ` blockquote line right after the badges
+
+## Sections
+✓ All required sections present
+✗ "Building Locally" appears before "What's Inside" — swap their order
+
+## Install
+✓ Four PM blocks present
+✗ Yarn block uses `yarn install` instead of `yarn add {{NAME}}`
+
+…
+
+## Suggested fixes
+1. Insert tagline after badges: `> {{description from package.json}}`
+2. Reorder sections so "What's Inside" comes before "Building Locally"
+3. Replace the yarn install command with `yarn add {{NAME}}`
+```
+
+## Auto-fix mode
+
+If the user explicitly asked to "fix" or "audit and fix" the README:
+
+1. Run the audit and produce the report first.
+2. Apply each `✗` finding using the verbatim templates from the
+   `readme-author` skill.
+3. **Never** rewrite the Maintainers HTML table — only fix the section
+   heading if it's missing.
+4. Show the diff and ask the user to confirm before saving in cases where
+   the original had hand-written content (About, What's Inside, Description)
+   that you'd be discarding.

package/dist/plugins/xy-readme/skills/readme-author/SKILL.md

@@ -0,0 +1,293 @@
+---
+name: readme-author
+description: Author or update a package README in the xylabs / xyo monorepo style. Use when creating a new package's README, filling in body content for an existing one, or adapting a README from a different style. Activates when working on any README.md inside a package directory under xylabs/ or XYOracleNetwork/ repos.
+---
+
+# README Author (xylabs / xyo convention)
+
+This skill produces package READMEs that match the convention used across
+`xylabs/*` and `XYOracleNetwork/*` monorepos. The convention is documented
+**by example**, not by a generator — there is no `xy readme:gen` command.
+Author the file directly using the templates below.
+
+## When to use
+
+- Creating a new package's `README.md`.
+- Updating an existing README that already follows the convention.
+- Migrating a README from a different style into this one.
+
+If the user just wants a one-line description added to an existing README
+section, do that directly — don't reflow the whole file.
+
+## Section order (required)
+
+Every package README MUST have these sections in this order. Skip optional
+sections only if they truly don't apply.
+
+1. **Logo + Title**
+2. **Badges** (npm version + license)
+3. **Tagline** (one-line `> blockquote`)
+4. **Table of Contents** *(aggregate-tier only)*
+5. **About** *or* **Description** (aggregate uses "Description")
+6. **Install** (4 package-manager blocks)
+7. **Subpath Exports** *(only if the package exposes them)*
+8. **Quick Start** *(aggregate-tier only, optional)*
+9. **What's Inside**
+10. **Peer Dependencies** *(only if the package has notable peer deps)*
+11. **Building Locally**
+12. **Maintainers** (HTML table — see "Maintainers rule" below)
+13. **License**
+14. **Credits**
+15. **Reference Link Definitions** (at end of file)
+
+## Tier detection
+
+Pick the tier from `package.json` and the package's role:
+
+- **Aggregate** — umbrella package that re-exports siblings. Usually has many
+  `dependencies` on workspace siblings, few or no implementation files of its
+  own. Add a Table of Contents and use "Description" instead of "About".
+- **Mid-tier** — implementation package with substantial surface area; may
+  expose subpath exports. Use "About" + optional "Subpath Exports" + "What's
+  Inside".
+- **Leaf** — single-purpose package, small surface. Use "About" + "What's
+  Inside" (often very short). May add "Peer Dependencies" if relevant.
+
+## Templates
+
+### Header (verbatim, all tiers)
+
+Replace `{{NAME}}` with the full package name (e.g.
+`@xyo-network/xl1-blockies`) and `{{TAGLINE}}` with a one-line description.
+
+```markdown
+[![logo][]][logo-link]
+
+# {{NAME}}
+
+[![npm-badge][]][npm-link]
+[![license-badge][]][license-link]
+
+> {{TAGLINE}}
+```
+
+### Table of Contents (aggregate only)
+
+```markdown
+## Table of Contents
+
+- [Description](#description)
+- [Install](#install)
+- [Subpath Exports](#subpath-exports)
+- [What's Inside](#whats-inside)
+- [Building Locally](#building-locally)
+- [Maintainers](#maintainers)
+- [License](#license)
+- [Credits](#credits)
+```
+
+Adjust the entries to match the actual sections present in the file.
+
+### About / Description (1–3 paragraphs, hand-written)
+
+Mid-tier and leaf packages use `## About`. Aggregate packages use
+`## Description`. Explain in plain prose:
+
+- What this package is.
+- How it relates to its umbrella aggregate (link to the aggregate package on
+  npm using its full URL: `https://www.npmjs.com/package/{{aggregate-name}}`).
+- When a consumer should install this package directly vs. install the
+  aggregate.
+
+Do not bullet this section. Prose only.
+
+### Install (verbatim, all tiers)
+
+The Install section ALWAYS uses these four blocks in this exact order, each
+prefaced with a `Using <pm>:` line. Always use `sh` as the code-block language.
+
+````markdown
+## Install
+
+Using npm:
+
+```sh
+npm i --save {{NAME}}
+```
+
+Using yarn:
+
+```sh
+yarn add {{NAME}}
+```
+
+Using pnpm:
+
+```sh
+pnpm add {{NAME}}
+```
+
+Using bun:
+
+```sh
+bun add {{NAME}}
+```
+````
+
+### Subpath Exports (when applicable)
+
+```markdown
+## Subpath Exports
+
+- `{{NAME}}` — main barrel
+- `{{NAME}}/get` — cosmiconfig integration; heavier deps kept separate
+- `{{NAME}}/test` — shared test utilities
+```
+
+Match the bullets to the actual `exports` map in `package.json`. One line per
+export, with a short reason for each subpath when it isn't obvious.
+
+### What's Inside
+
+Hand-written, package-specific. Use bullets, **bold** category labels, and
+em-dashes. Keep each bullet to one or two sentences. Examples:
+
+```markdown
+## What's Inside
+
+- **Simple\*** — ~26 high-level implementations (`SimpleBlockRunner`,
+  `SimpleMempoolViewer`, …) composing lower-level pieces
+- **Services** — `ChainService`, `ChainHeadService`, `Election`, …
+- **Wallets** — HD wallet derivation from mnemonic
+```
+
+For leaf packages, this section can be just two or three bullets describing
+the public surface.
+
+### Peer Dependencies (when applicable)
+
+```markdown
+## Peer Dependencies
+
+This package targets {{stack-summary}}. See [`package.json`](./package.json)
+for the exact `peerDependencies` ranges.
+```
+
+### Building Locally (verbatim)
+
+Always three commands scoped to the package:
+
+````markdown
+## Building Locally
+
+```sh
+xy build {{NAME}}
+xy test {{NAME}}
+xy lint {{NAME}}
+```
+````
+
+The aggregate-tier root `README.md` may use the unscoped form
+(`xy build`, etc.) followed by a "Scope to this package: …" sentence — but
+package READMEs always scope.
+
+### Maintainers (verbatim — see "Maintainers rule" below)
+
+```markdown
+## Maintainers
+
+<table>
+  <tr>
+    <td align="center" valign="top" width="120">
+      <a href="https://github.com/arietrouw">
+        <img src="https://github.com/arietrouw.png" width="80" height="80" alt="Arie Trouw" /><br />
+        <sub><b>Arie Trouw</b></sub>
+      </a>
+      <br />
+      <a href="https://arietrouw.com">arietrouw.com</a>
+    </td>
+    <td align="center" valign="top" width="120">
+      <a href="https://github.com/jonesmac">
+        <img src="https://github.com/jonesmac.png" width="80" height="80" alt="Matt Jones" /><br />
+        <sub><b>Matt Jones</b></sub>
+      </a>
+    </td>
+    <td align="center" valign="top" width="120">
+      <a href="https://github.com/JoelBCarter">
+        <img src="https://github.com/JoelBCarter.png" width="80" height="80" alt="Joel Carter" /><br />
+        <sub><b>Joel Carter</b></sub>
+      </a>
+    </td>
+  </tr>
+</table>
+```
+
+### License (verbatim)
+
+```markdown
+## License
+
+See the [LICENSE](./LICENSE) file (LGPL-3.0-only).
+```
+
+The aggregate-tier root README may use the longer form:
+`See the [LICENSE](./LICENSE) file for license rights and limitations (LGPL-3.0-only).`
+
+### Credits (verbatim)
+
+```markdown
+## Credits
+
+[Made with 🔥 and ❄️ by XYO](https://xyo.network)
+```
+
+### Reference Link Definitions (verbatim, at end of file)
+
+Replace `{{NAME}}` with the package name. The blocks are separated by blank
+lines and appear in this order.
+
+```markdown
+[logo]: https://cdn.xy.company/img/brand/XYO_full_colored.png
+[logo-link]: https://xyo.network
+
+[npm-badge]: https://img.shields.io/npm/v/{{NAME}}.svg
+[npm-link]: https://www.npmjs.com/package/{{NAME}}
+
+[license-badge]: https://img.shields.io/npm/l/{{NAME}}.svg
+[license-link]: ./LICENSE
+```
+
+## Maintainers rule
+
+The Maintainers HTML table is static and managed by humans. **Do not modify
+it** unless the user explicitly asks you to add, remove, or update someone.
+When creating a brand-new README, copy the verbatim table above as the
+default — the user can edit it later.
+
+## Style rules
+
+- Only one `# H1` in the file: the title under the logo. Body sections start
+  at `## H2`.
+- Always use `sh` as the language for shell code blocks.
+- Use no language hint on TypeScript snippets unless the snippet is short and
+  benefits from highlighting (in which case use `ts`).
+- Prefer relative links for in-repo references (`./LICENSE`,
+  `[`package.json`](./package.json)`).
+- Cross-package references on npm use the full URL
+  `https://www.npmjs.com/package/{{NAME}}`.
+- Reference-style links for badges and the logo. Inline links are fine for
+  one-off references in prose.
+- Em-dash (`—`) separates a bold label from its description in `What's Inside`
+  bullets.
+- Keep section bodies tight. The README is an entry point, not a manual.
+
+## Author / update workflow
+
+1. Read `package.json` — extract `name`, `description`, and any `exports` keys.
+2. Determine tier (aggregate / mid-tier / leaf).
+3. If updating an existing README: identify which sections already exist and
+   preserve any hand-written content the user added. Don't overwrite the
+   Maintainers table.
+4. Assemble the file in the section order above using the templates.
+5. Verify all reference-link definitions at the bottom match the inline uses.
+6. Double-check there is exactly one `# H1` and no stray heading levels.