feat(bulma-ui): ship agent-discovery files in the npm tarball

[allxsmith]

Pull Request

Description

Makes @allxsmith/bestax-bulma discoverable to AI agents that explore the installed package in node_modules (the sandboxed, package-first workflow that misses the README and the docs site). Layered so every probe path — filename probe, dist grep, types read, package.json read — lands on a pointer to the docs site, the skills, and the create-bestax scaffolder:

• Pointer files in the tarball: llms.txt and AGENTS.md at the package root (added to files), plus a consumer-facing CLAUDE.md. Since bulma-ui/CLAUDE.md is the internal contributor file, a new prepack/postpack script (bulma-ui/scripts/pack-pointer-files.mjs) backs it up, packs a copy of AGENTS.md in its place, and restores it afterward — verified with an npm pack round-trip (tarball CLAUDE.md equals AGENTS.md; working tree restored, no backup left).

• Grep-able banner: one-line AI banner on dist/index.esm.js / dist/index.cjs.js via rollup output.banner.

• JSDoc in shipped types: dropped removeComments: true from the rollup TypeScript plugin, so the extensive source JSDoc (e.g. Theme's bulmaVars/isRoot/colorMode @property blocks) now reaches dist/types/*.d.ts — also fixes IDE hover docs. Consumer prod bundles are unaffected (minifiers strip comments; bundlephobia measures minified size).

• package.json signals: keywords ai, llms, agents, agent-skills.

• README: "For AI Tools" section now mentions the shipped pointer files and lists all seven skills (table previously showed four).

• URL check: scripts/check-pointer-urls.mjs + a CI step so a release cannot ship dead links in the pointer files.

• docs: "In the npm package" section in the LLMs guide; skills install block updated to all seven skills.

• create-bestax fix: bestax-migrate was missing from sync-skills.mjs's hardcoded list, so scaffolded apps got six of the seven skills; added there and to the scaffolded CLAUDE.md roster.

• bulma-ui (@allxsmith/bestax-bulma)

• create-bestax (create-bestax)

• docs (@allxsmith/bestax-docs)

• Other (please specify):

Related Issue(s)

Closes #344

Type of Change

• New feature
• Bug fix
• Documentation
• Build tooling

Checklist

• My code follows the project style guidelines
• I have performed a self-review of my code
• I have added tests that prove my fix is effective or that my feature works
• I have added/updated documentation as needed
• I have updated Storybook stories as needed (bulma-ui)
• My changes require a change to the documentation
• All new and existing tests passed
• Any relevant dependencies are updated
• If this PR changes commands, conventions, or package structure, the affected CLAUDE.md files are updated

Notes: no component/API changes, so no new tests or stories; packaging was verified with an npm pack round-trip and the full pnpm all gate. The published-package behavior (pointer files, banner, JSDoc-bearing types) is documented in the README and the LLMs guide.

Screenshots / Demos

Tarball listing after the change (npm pack --dry-run):

npm notice 1.2kB AGENTS.md
npm notice 1.2kB CLAUDE.md
npm notice 349B  llms.txt

First line of each dist bundle:

/* @allxsmith/bestax-bulma — AI agents: see AGENTS.md in the package root, or https://bestax.io/llms.txt */

Additional Context

The new "Pointer file URLs resolve" CI step needs outbound network to bestax.io; it passes from GitHub runners (the URLs are the site's stable generated artifacts). The pointer files are deliberately pointers, not documentation — the site artifacts remain the single source of truth, so nothing in the tarball goes stale between releases.

🤖 Generated with Claude Code

https://claude.ai/code/session_015rabYH1o5wYDyqQXbU4gDH

---

Generated by Claude Code

Summary by CodeRabbit

• New Features

  • Published packages now include AI and agent guidance files, including llms.txt and AGENTS.md.
  • Added documentation and metadata for available agent skills, including icons, optimization, and migration guidance.
  • Generated bundles now include attribution information.

• Documentation

  • Expanded LLM and agent setup guidance for Bulma UI and newly created apps.

• Chores

  • Added automated validation to confirm documentation links resolve correctly during CI checks.

[coderabbitai]

Walkthrough

The package now ships agent-facing pointer files, adds package and bundle discoverability signals, includes the missing bestax-migrate skill in related scaffolding, temporarily generates the published CLAUDE.md, and verifies pointer URLs locally and in CI.

Changes

Agent discoverability

Layer / File(s)	Summary
Agent pointer content and skill references bulma-ui/AGENTS.md, bulma-ui/llms.txt, bulma-ui/README.md, docs/docs/guides/llms/index.md, create-bestax/...	Adds package-level agent documentation and URL pointers, documents the published files, and adds bestax-icons, bestax-optimize, and bestax-migrate references.
Pointer-file packaging lifecycle bulma-ui/package.json, bulma-ui/scripts/pack-pointer-files.mjs, .gitignore	Publishes the pointer files and swaps CLAUDE.md with AGENTS.md during prepack, then restores it during postpack.
Bundle and type documentation signals bulma-ui/rollup.config.js	Adds an AI pointer banner to CJS and ESM bundles and preserves TypeScript comments.
Pointer URL verification scripts/check-pointer-urls.mjs, package.json, .github/workflows/ci.yml	Checks HTTPS URLs from pointer files with HEAD and GET, exposes the check as check:urls, and runs it in CI.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant CI
  participant check_urls as check-pointer-urls.mjs
  participant pointer_files as llms.txt and AGENTS.md
  CI->>check_urls: Run pnpm run check:urls
  check_urls->>pointer_files: Read HTTPS URLs
  check_urls->>check_urls: Issue HEAD then GET requests
  check_urls-->>CI: Exit successfully or report unresolved URLs

Loading

Possibly related PRs

• allxsmith/bestax#268 — Related pointer-file packaging and URL verification work.
• allxsmith/bestax#271 — Related CLAUDE.md generation changes.
• allxsmith/bestax#310 — Related skills synchronization changes.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly matches the main change: shipping agent-discovery files in the bulma-ui npm tarball.
Description check	✅ Passed	The description covers the required summary, affected packages, issue reference, change type, checklist, and context.
Linked Issues check	✅ Passed	The PR implements the #344 requirements: tarball pointer files, bundle banners, preserved JSDoc, keywords, CI URL checks, and the create-bestax skill fix.
Out of Scope Changes check	✅ Passed	The shown changes stay aligned with the agent-discovery and packaging goals, with no clear unrelated scope added.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/agent-discovery-npm-tarball-qvdkz5

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 Checkov (3.3.8)

.github/workflows/ci.yml

Traceback (most recent call last):
File "/usr/local/bin/checkov", line 2, in
from checkov.main import Checkov
ModuleNotFoundError: No module named 'checkov'

bulma-ui/package.json

Traceback (most recent call last):
File "/usr/local/bin/checkov", line 2, in
from checkov.main import Checkov
ModuleNotFoundError: No module named 'checkov'

package.json

Traceback (most recent call last):
File "/usr/local/bin/checkov", line 2, in
from checkov.main import Checkov
ModuleNotFoundError: No module named 'checkov'

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint install timed out. The project may have too many dependencies for the sandbox.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Preview Deployment

Preview URL: https://bc433665.bestax.pages.dev

[claude]

Required CI now depends on external network reachability — 🟡 Minor · Correctness

What: check:urls lives in the main build-and-test job, which runs on every push and every pull_request. It makes ~5 live HTTP requests to bestax.io (and github.com) with a 10s timeout, and a non-res.ok/timeout/DNS blip fails the whole job — process.exit(1).

Why it matters: A required status check is now coupled to third-party uptime. If the docs site is briefly down, slow (>10s), or mid-deploy, unrelated PRs that don't touch any pointer file get a red CI and are blocked until someone re-runs. Release-time link rot is worth catching, but paying that cost on every PR trades determinism for external flakiness.

Secondary caveat: Docusaurus soft-404s (SPA fallback returning 200 for unknown paths) mean a genuinely dead …/foo.md link can still pass res.ok, so the check also gives false confidence — worth a status-body assertion if you keep it.

Fix: run it only where it pays off — the release/publish job, or gate on pointer-file changes:

      - name: Pointer file URLs resolve
        if: github.event_name == 'push'   # skip per-PR; still gates main before release
        run: pnpm run check:urls

Alternative: path-filtered

Use dorny/paths-filter (or a changed-files action) and only run when bulma-ui/llms.txt or bulma-ui/AGENTS.md changed, so contributors touching unrelated code never hit a network flake. Adding continue-on-error: true would also de-risk it, at the cost of making the gate advisory.

[claude]

Deep review — 1 finding

#	Severity	Area	Finding	Location
1	🟡 Minor	Correctness	check:urls runs on every PR/push, coupling a required check to bestax.io/github.com uptime; soft-404s can also mask dead links	.github/workflows/ci.yml:72

Overall: The change is sound and low-risk — it ships pointer files (llms.txt/AGENTS.md/CLAUDE.md) in the tarball, adds a grep-able AI banner, and backfills the missing bestax-migrate skill. I verified the swap mechanism (no ignore-scripts in .npmrc, the git commit precedes publish, and an interrupted pack is guarded so the internal contributor CLAUDE.md can't leak or get committed), confirmed the 7-skill roster is consistent across README, AGENTS.md, sync-skills.mjs, and constants.ts, and checked that no snapshot test asserts the skill count. The riskiest part is operational, not correctness: the new URL check in the shared build-and-test job introduces an external network dependency into a required gate — the human should decide whether to move it to the release job or gate it on pointer-file changes.

🏄 Mellow set, dude — just some signposts nailed to the tarball so wandering agents don't wipe out in node_modules. Clean paddle-out, only ripple is that URL-checker leashing every PR to the docs site's mood. Trim that and it's a smooth glass ride to merge. 🌊

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.github/workflows/ci.yml:
- Around line 72-74: Update the “Pointer file URLs resolve” workflow step
running check:urls so live-production URL failures on pull requests do not block
valid documentation changes, while preserving URL validation where appropriate.
Also verify this .github workflow change complies with the project’s
autonomous-loop restrictions and adjust the workflow configuration if needed.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 641cc81c-7c58-4a11-9ca8-852f532ecec1

📥 Commits

Reviewing files that changed from the base of the PR and between 44f987d and dbee307.

📒 Files selected for processing (13)

• .github/workflows/ci.yml
• .gitignore
• bulma-ui/AGENTS.md
• bulma-ui/README.md
• bulma-ui/llms.txt
• bulma-ui/package.json
• bulma-ui/rollup.config.js
• bulma-ui/scripts/pack-pointer-files.mjs
• create-bestax/scripts/sync-skills.mjs
• create-bestax/src/constants.ts
• docs/docs/guides/llms/index.md
• package.json
• scripts/check-pointer-urls.mjs

[coderabbitai]

📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win

Address the documentation deployment hazard and verify workflow policies.

This CI step introduces two potential blockers for pull requests:

1. Chicken-and-egg hazard: Because the checker validates live production URLs (https://bestax.io/...), PRs that introduce new documentation pages will fail this step (the URLs will return 404 since the pages won't be deployed to production until the PR merges). Consider using continue-on-error for PRs to prevent blocking valid changes.
2. AI-loop protections: As per coding guidelines, the autonomous loop refuses changes touching .github/** and related test configuration. Please ensure this addition will not cause the PR to be rejected by the loop.

🛠 Proposed fix for the deployment hazard

       - name: Pointer file URLs resolve
+        # Prevent 404s on new, undeployed docs from blocking PRs
+        continue-on-error: ${{ github.event_name == 'pull_request' }}
         run: pnpm run check:urls

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	- name: Pointer file URLs resolve
	run: pnpm run check:urls
	- name: Pointer file URLs resolve
	# Prevent 404s on new, undeployed docs from blocking PRs
	continue-on-error: ${{ github.event_name == 'pull_request' }}
	run: pnpm run check:urls

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.github/workflows/ci.yml around lines 72 - 74, Update the “Pointer file URLs
resolve” workflow step running check:urls so live-production URL failures on
pull requests do not block valid documentation changes, while preserving URL
validation where appropriate. Also verify this .github workflow change complies
with the project’s autonomous-loop restrictions and adjust the workflow
configuration if needed.

Source: Coding guidelines

[github-actions]

🎉 This PR is included in version 5.8.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[github-actions]

🎉 This PR is included in version 3.6.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[bestax-release-bot]

🎉 This PR is included in version 2.0.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[bestax-release-bot]

🎉 This PR is included in version 1.0.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀