chore(repo): track .pi/, apply RFC 2119, clean up skills and prompts

.gitignore

@@ -45,10 +45,7 @@ next-env.d.ts
 
 # local agent/tooling artifacts
 .agents/
-.pi/
-prompts/
-docs-component-format-spec.md
-AGENTS.md
+
 skills-lock.json
 bun.lock
 .env.local

.pi/prompts/README.md

@@ -0,0 +1,17 @@
+# jal-co/ui Prompts
+
+Repo-aware prompts for creating, reviewing, and ideating jalco ui registry content.
+
+## Prompts
+
+- `/component-create` — create a new component, block, or registry item through the standard workflow
+- `/component-review` — audit an existing component against the jalco ui quality bar
+- `ideate-jalco-components.md` — ideate new additions based on the current repo state
+
+## How they work
+
+Each prompt:
+- reads the repo first (AGENTS.md, registry.json, existing patterns)
+- consults local skills before generating output
+- acts as an implementation/review partner, not a generic text generator
+- follows Conventional Branch naming for feature branches

.pi/prompts/component-create.md

@@ -0,0 +1,50 @@
+# /component-create
+
+Build a new jalco ui component through the standard repository workflow.
+
+<context>
+Use this prompt when the user wants to create a new component, block, registry item, or docs-facing UI artifact.
+</context>
+
+<instructions>
+
+1. Create a feature branch: `feat/<component-name>`.
+2. Read `.pi/skills/jalco-component-builder/SKILL.md` first and treat it as the primary workflow.
+3. If the request is underspecified, use the `question` or `questionnaire` tool to clarify the component before coding.
+4. Use concise, Socratic questioning to determine:
+   - the core use case
+   - whether this is a primitive, composed component, or block
+   - whether it belongs in the public registry, docs site only, or both
+   - the intended default feel and strongest default state
+   - the minimum public API
+   - which variants are truly justified
+   - whether the component should stay in one file
+   - whether any dependency is genuinely needed
+5. SHOULD prefer a single-file implementation unless multiple files materially improve readability, runtime correctness, reuse, or installability.
+6. Use supporting references named in `jalco-component-builder` as needed, especially for shadcn ergonomics, Tailwind v4 patterns, composition, React/Next implementation quality, and accessibility.
+7. Reuse established Jalco and shadcn variant language when appropriate, but MUST NOT add variants mechanically.
+8. SHOULD prefer strong default styling, realistic preview content, and restrained visual treatment over decorative complexity.
+9. If this is a public component, MUST update the docs, preview/demo coverage, and any relevant registry metadata in the same change.
+10. MUST create a catalog card preview at `components/docs/previews/<registry-name>.tsx` showing key variants, and run `pnpm previews:generate`.
+11. MUST add the sidebar nav entry in `lib/docs.ts` with `badge: "New"` and `badgeAdded` set to today's ISO date.
+12. MUST generate screenshots via `/dev/screenshots` — save `<name>-dark.png` and `<name>-light.png` to `public/previews/`.
+13. MUST run `pnpm registry:build` and `pnpm build` to verify.
+14. MUST open a PR using the component template and attach dark/light screenshots.
+15. MUST keep comments compact and useful. Use Jalco-style file headers when appropriate. MUST NOT add decorative separator banners.
+
+</instructions>
+
+<format>
+
+## Output expectations
+
+Before implementing, briefly state:
+- the component's use case
+- the proposed API shape
+- the justified variants
+- the one-file vs multi-file decision
+- any dependency decision
+
+Then implement the component and related docs updates.
+
+</format>

.pi/prompts/component-review.md

@@ -0,0 +1,46 @@
+# /component-review
+
+Audit a jalco ui component using the repository's public component quality bar.
+
+<context>
+Use this prompt when the user wants feedback on an existing component, registry item, docs-facing component, preview, or public API.
+</context>
+
+<instructions>
+
+1. MUST read `.pi/skills/jalco-component-builder/SKILL.md` first and use it as the review rubric.
+2. MUST inspect the component source, related demos/previews, and relevant docs before judging quality.
+3. Evaluate the component for:
+   - clarity of use case
+   - quality of the default state
+   - visual hierarchy and restraint
+   - API size and semantic clarity
+   - variant discipline
+   - one-file vs multi-file appropriateness
+   - dependency justification
+   - accessibility and copy-paste ergonomics
+   - alignment across implementation, preview, docs, and registry metadata
+   - presence of a catalog card preview file in `components/docs/previews/`
+   - sidebar nav entry in `lib/docs.ts`
+4. MUST be direct and critical when needed. MUST NOT praise weak work just because it is technically valid.
+5. If recommending changes, prioritize:
+   - what SHOULD be removed or simplified
+   - which variants SHOULD be merged or cut
+   - whether the file structure SHOULD be collapsed
+   - whether dependencies SHOULD be avoided
+   - how the default example SHOULD be improved
+
+</instructions>
+
+<format>
+
+## Output structure
+
+1. What feels strong
+2. What feels off or generic
+3. API and variant issues
+4. File structure and dependency issues
+5. Recommended changes in priority order
+6. Whether the component is ready for jalco ui in its current form
+
+</format>

.pi/prompts/ideate-jalco-components.md

@@ -0,0 +1,78 @@
+# /ideate-jalco-components
+
+Ideate new jalco ui additions based on repository context and gaps.
+
+<context>
+
+Before ideating, MUST read these files:
+- `AGENTS.md`
+- `README.md`
+- `registry.json`
+- `app/page.tsx`
+- `.pi/skills/vercel-react-best-practices/SKILL.md`
+- `.pi/skills/vercel-composition-patterns/SKILL.md`
+- `.pi/skills/tailwind-design-system/SKILL.md`
+
+Then inspect the current registry items and identify what categories, use cases, or quality levels are missing.
+
+</context>
+
+<instructions>
+
+## Task
+
+Help ideate new jalco ui additions based on this context:
+
+{{IDEATION_CONTEXT}}
+
+## Ideation goals
+
+Suggested additions MUST be:
+- practical
+- installable
+- visually strong
+- differentiated from generic examples
+- documentation-friendly
+- aligned with jalco ui's brand and quality bar
+
+Consider whether each idea is best as a:
+- component
+- block
+- hook
+- pattern
+- docs concept
+
+## Required process
+
+1. MUST read the required files first.
+2. MUST inspect the current registry and surface obvious gaps.
+3. SHOULD propose ideas that balance usefulness, visual appeal, and implementation value.
+4. SHOULD prioritize ideas that would make jalco ui more distinctive.
+5. SHOULD call out quick wins versus longer-term standout additions.
+
+</instructions>
+
+<format>
+
+## Output format
+
+Return these sections:
+
+1. **Current gap summary**
+2. **Top 10 proposed additions**
+   - name
+   - type
+   - what it does
+   - why it belongs in jalco ui
+   - implementation complexity: low / medium / high
+   - docs/demo appeal: low / medium / high
+3. **Best 3 quick wins**
+4. **Best 3 standout additions**
+5. **Suggested build order**
+6. **Docs categories these ideas support**
+
+</format>
+
+<constraints>
+Optimize for additions that would make jalco ui feel curated, not bloated.
+</constraints>

.pi/references/docs-component-format-spec.md

@@ -0,0 +1,125 @@
+# Component Docs Format Spec
+
+Canonical reference for the structure, section order, writing rules, and review checklist of jalco ui component documentation pages.
+
+## Page anatomy
+
+Every component docs page MUST use `ComponentDocsPage` from `components/docs/component-docs-page.tsx` and follow this section order:
+
+1. **Metadata** — `export const metadata: Metadata` with `title` and `description`
+2. **Header** — rendered by `ComponentDocsPage`: title, description, AiCopyButton, DependencyBadges
+3. **Preview** — live component inside `ComponentPreview` with source file tabs
+4. **Installation** — `InstallCommand` with registry name; `installNote` for bundled exports
+5. **Usage** — import snippet via `CodeLine`, minimal usage example, server/client rendering context
+6. **Children** (optional, order as needed):
+   - Playground
+   - Examples (variants, sizes, configurations, etc.)
+   - API Reference
+   - Notes
+
+## ComponentDocsPage props
+
+| Prop | Type | Required | Purpose |
+|---|---|---|---|
+| `title` | `string` | yes | Display name (e.g. "GitHub Stars Button") |
+| `description` | `string` | yes | One-sentence summary |
+| `registryName` | `string` | no | Registry item name; enables install block and badges |
+| `sourceFiles` | `(string \| { path, name?, language? })[]` | no | Source file paths for the code tab |
+| `preview` | `ReactNode` | no | Live component for the Preview section |
+| `installNote` | `ReactNode` | no | Note below install command (e.g. bundled-in explanation) |
+| `usage` | `ReactNode` | no | Usage section content |
+| `children` | `ReactNode` | no | Everything after Usage |
+
+## Writing rules
+
+### Descriptions
+
+- MUST be one sentence, capability-first
+- MUST NOT start with "A", "An", or "A React component for..."
+- MUST NOT contain implementation details, subjective adjectives, or unnecessary jargon
+- MUST match across: page `metadata.description`, `ComponentDocsPage` `description` prop, and `registry.json` description
+
+### Usage section
+
+- MUST include an import snippet via `CodeLine`
+- MUST include a minimal usage example via `CodeLine`
+- Server/client rendering context MUST be stated here (e.g. "Async server component")
+- The first example SHOULD be minimal — layer complexity in the Examples section
+
+### Examples section
+
+- MUST use `VariantGrid` with labeled items when showing multiple visual states
+- MUST group items by meaning: Variants, Sizes, Icon Styles, Configurations, etc.
+- MUST NOT label everything as a "variant" — use the most accurate grouping label
+- SHOULD use realistic, polished content over placeholder text
+
+### Playground section
+
+- MAY be included when the component has multiple interactive props worth exploring
+- SHOULD be a client component that lets users toggle props and see results
+
+### API Reference section
+
+- SHOULD be included when the component has a non-obvious public API
+- MUST use `ApiRefTable` from `registry/api-ref-table/api-ref-table`
+- SHOULD list all public props with name, type, required flag, and description
+
+### Notes section
+
+- MUST contain only caveats, limitations, and external service behavior
+- MUST NOT contain architecture decisions, feature highlights, or rendering context
+- SHOULD be brief — a short bulleted list
+
+### Bundled exports
+
+- When a component is bundled inside another registry item, MUST use `installNote` to explain
+- MUST set `bundledIn` on the nav item in `lib/docs.ts`
+
+## Section heading style
+
+All `<h2>` headings inside `ComponentDocsPage` children MUST use:
+
+```tsx
+<h2 className="text-xl font-semibold tracking-tight">Section Title</h2>
+```
+
+Sub-headings (`<h3>`) inside example groups MUST use:
+
+```tsx
+<h3 className="text-base font-medium">Group Label</h3>
+```
+
+## Naming alignment
+
+These MUST all refer to the same artifact using consistent naming:
+- page `metadata.title`
+- `ComponentDocsPage` `title` prop
+- `registry.json` item `title`
+- sidebar nav title in `lib/docs.ts`
+- preview file name in `components/docs/previews/`
+- component export name
+
+## File header and comment rules
+
+- Public Jalco-authored component source files SHOULD use the compact Jalco-style header
+- Headers MUST be compact and human-written in tone
+- Headers MUST NOT duplicate the docs page content
+- Decorative separator banners MUST NOT appear in source code
+- Inline comments MUST be minimal and useful
+- Comments MUST NOT narrate straightforward code
+
+## Review checklist
+
+Before shipping a component docs page, verify:
+
+- [ ] Page uses `ComponentDocsPage`
+- [ ] `metadata.description` matches `ComponentDocsPage` `description` and `registry.json`
+- [ ] Preview renders a realistic default state
+- [ ] Usage includes import, minimal example, and server/client context
+- [ ] Examples use `VariantGrid` with accurate group labels
+- [ ] Notes contains only caveats (no features, no architecture)
+- [ ] Sidebar entry in `lib/docs.ts` is correct (title, order, badge, bundledIn)
+- [ ] Card preview exists at `components/docs/previews/<registry-name>.tsx`
+- [ ] Screenshots exist at `public/previews/<name>-dark.png` and `<name>-light.png`
+- [ ] `pnpm previews:generate` has been run
+- [ ] `pnpm registry:build` and `pnpm build` pass