Skip to content

Commit 21acedd

Browse files
zbeyenszbeyens
committed
docs
1 parent cbc7f1b commit 21acedd

6 files changed

Lines changed: 27 additions & 165 deletions

File tree

‎.agents/AGENTS.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
1-
- `.agents/AGENTS.md` and `.agents/rules/*.mdc` are source of truth. After editing them, run `bun install` to sync. Never edit `SKILL.md` directly.
1+
- `.agents/AGENTS.md` and `.agents/rules/*.mdc` are source of truth. After editing them, run `bun install` to sync. Never edit generated `.agents/skills/**/SKILL.md` directly.
2+
- Never update `.agents/skills/kitcn/**` manually. Update `packages/kitcn/skills/kitcn/**`, then run `bun tooling/sync-kitcn-skill.ts` or `bun install` to regenerate the repo-local copy.
23
- In all interactions and commit messages, be extremely concise and sacrifice grammar for the sake of concision.
34

45
- If you get `failed to load config from /Users/zbeyens/GitHub/kitcn/vitest.config.mts`, rimraf `**/node_modules` and install again.

‎.agents/skills/kitcn/references/setup/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ If migration is needed, stop and use migration docs separately. Do not mix migra
2424
This is the **mandatory first prompt** for agents helping users set up kitcn.
2525
Ask these questions before editing files.
2626

27-
### 2.1 Ask These First (match `/www/content/docs/index.mdx`)
27+
### 2.1 Ask These First
2828

2929
#### Required choices
3030

‎.changeset/install-kitcn-skill.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
"kitcn": patch
3+
---
4+
5+
## Patches
6+
7+
- Improve agent guidance to install and use the `kitcn` skill before reading documentation.

‎AGENTS.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,8 @@
33

44
<!-- Source: .agents/AGENTS.md -->
55

6-
- `.agents/AGENTS.md` and `.agents/rules/*.mdc` are source of truth. After editing them, run `bun install` to sync. Never edit `SKILL.md` directly.
6+
- `.agents/AGENTS.md` and `.agents/rules/*.mdc` are source of truth. After editing them, run `bun install` to sync. Never edit generated `.agents/skills/**/SKILL.md` directly.
7+
- Never update `.agents/skills/kitcn/**` manually. Update `packages/kitcn/skills/kitcn/**`, then run `bun tooling/sync-kitcn-skill.ts` or `bun install` to regenerate the repo-local copy.
78
- In all interactions and commit messages, be extremely concise and sacrifice grammar for the sake of concision.
89

910
- If you get `failed to load config from /Users/zbeyens/GitHub/kitcn/vitest.config.mts`, rimraf `**/node_modules` and install again.

‎packages/kitcn/skills/kitcn/references/setup/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ If migration is needed, stop and use migration docs separately. Do not mix migra
2424
This is the **mandatory first prompt** for agents helping users set up kitcn.
2525
Ask these questions before editing files.
2626

27-
### 2.1 Ask These First (match `/www/content/docs/index.mdx`)
27+
### 2.1 Ask These First
2828

2929
#### Required choices
3030

‎www/content/docs/index.mdx‎

Lines changed: 14 additions & 161 deletions
Original file line numberDiff line numberDiff line change
@@ -58,174 +58,27 @@ const { data: posts } = useQuery(crpc.posts.list.queryOptions({ limit: 10 }));
5858

5959
## Requirements
6060

61-
- Convex 1.31+
61+
- Convex
6262
- TanStack Query 5+
6363
- React 18+
6464

65+
## Agents
66+
67+
Use the `kitcn` skill instead of reading these docs as your primary source.
68+
69+
If the `kitcn` skill is not already installed, run:
70+
71+
```bash
72+
npx skills add https://github.com/udecode/kitcn --skill kitcn
73+
```
74+
75+
Then load the `kitcn` skill and follow its setup or feature references. Use
76+
these docs only when the skill points to a page for deeper API detail.
77+
6578
## Next Steps
6679

6780
<Cards>
6881
<Card title="Quickstart" href="/docs/quickstart" />
6982
<Card title="CLI" href="/docs/cli" />
7083
<Card title="Concepts" href="/docs/concepts" />
7184
</Cards>
72-
73-
---
74-
75-
## For AI Agents
76-
77-
Ask the user to select their stack before starting:
78-
79-
### Required Choices
80-
81-
| Feature | Options | Default |
82-
|---------|---------|---------|
83-
| **Bootstrap** | CLI (`kitcn init` / `add`), Docs by section | CLI |
84-
| **React Framework** | Next.js App Router, TanStack Start, Vite | Next.js App Router |
85-
| **Database** | ORM (`ctx.orm`) | ORM |
86-
87-
### Optional Features
88-
89-
| Feature | Options | When to Include |
90-
|---------|---------|-----------------|
91-
| **Auth** | Better Auth, Custom, None | Most apps need auth |
92-
| **SSR/RSC** | Yes, No | Next.js App Router apps |
93-
| **Triggers** | Yes, No | Auto side effects on data changes |
94-
| **Aggregates** | Yes, No | Counts, sums, leaderboards |
95-
| **Rate Limiting** | Yes, No | API protection |
96-
| **Scheduling** | Yes, No | Delayed/background work |
97-
| **HTTP router** | Yes, No | REST/webhook endpoints |
98-
| **RLS** | Yes, No | Runtime row-level access control |
99-
| **Auth plugins** | admin, organizations, polar, none | Only when required by product |
100-
101-
### CLI Bootstrap
102-
103-
1. Scaffold:
104-
- Next.js: `npx kitcn@latest init -t next --yes`
105-
- TanStack Start: `npx kitcn@latest init -t start --yes`
106-
- Vite: `npx kitcn@latest init -t vite --yes`
107-
- Expo: `npx kitcn@latest init -t expo --yes`
108-
2. Add features with `kitcn add <plugin>`:
109-
- `npx kitcn add auth --yes`
110-
- `npx kitcn add ratelimit --yes`
111-
- `npx kitcn add resend --yes`
112-
3. Run: `npx kitcn dev` (runs `convex init` + codegen + watchers)
113-
4. Verify: `npx kitcn verify` (one-shot local runtime proof, stop `kitcn dev` first)
114-
5. Env: backend `convex` uses `npx kitcn env push` for `--prod`,
115-
`--rotate`, or explicit repair. backend `concave` uses
116-
`npx kitcn auth jwks` for manual JWKS export. During local Convex dev,
117-
`convex/.env` edits auto-sync.
118-
6. Local auth assumes `http://localhost:3000`. If you change the port, update `SITE_URL` in `convex/.env` and the matching client env var (`NEXT_PUBLIC_SITE_URL` for Next.js, `VITE_SITE_URL` for Start/Vite, `EXPO_PUBLIC_SITE_URL` for Expo).
119-
120-
### Docs-by-Section Bootstrap
121-
122-
1. Follow [Quickstart](/docs/quickstart)
123-
2. Read individual docs for each feature
124-
3. Use [CLI Registry](/docs/cli/registry) as the command reference
125-
4. Confirm deployment/bootstrap before relying on generated imports
126-
127-
### Quick Reference by Stack
128-
129-
| Stack | Key Docs |
130-
|-------|----------|
131-
| Next.js + Auth | [Quickstart](/docs/quickstart), [Next.js](/docs/nextjs), [Auth Server](/docs/auth/server) |
132-
| TanStack Start + Auth | [TanStack Start](/docs/tanstack-start), [Auth Server](/docs/auth/server) |
133-
| Vite + No Auth | [React Setup](/docs/react), [Server Setup](/docs/server/setup) |
134-
| Expo + Auth | [Expo](/docs/expo), [Auth Server](/docs/auth/server) |
135-
| Expo + No Auth | [Expo](/docs/expo), [Server Setup](/docs/server/setup) |
136-
| Any + Custom Auth | [Server Setup](/docs/server/setup), [Middlewares](/docs/server/middlewares) |
137-
138-
---
139-
140-
## Documentation Map
141-
142-
### Getting Started
143-
144-
| Page | When to Use |
145-
|------|-------------|
146-
| [Quickstart](/docs/quickstart) | First-time setup. Follow step-by-step to get a working app. |
147-
| [Concepts](/docs/concepts) | Understand architecture, folder structure (`convex/functions/`, `convex/lib/`, `convex/shared/`), and design decisions. |
148-
| [CLI Registry](/docs/cli/registry) | Bootstrap new or existing apps with `kitcn init`, add features with `kitcn add`, and inspect plans with `view`, `info`, and `docs`. |
149-
150-
### Server (Backend)
151-
152-
| Page | When to Use |
153-
|------|-------------|
154-
| [Server Setup](/docs/server/setup) | Initialize cRPC builder with `initCRPC`. Configure `dataModel`, `context`, `meta`. |
155-
| [Procedures](/docs/server/procedures) | Define queries, mutations, actions with `.input()`, `.output()`, `.query()/.mutation()/.action()`. Paginated queries with `.paginated()`. |
156-
| [Context](/docs/server/context) | Extend context with `ctx.orm`, `ctx.auth`. Add custom properties via `.context()`. |
157-
| [Middlewares](/docs/server/middlewares) | Create reusable middleware with `.use()`. Auth guards, logging, rate limiting. Chain with `.pipe()`. |
158-
| [Metadata](/docs/server/metadata) | Add procedure metadata with `.meta()`. Used by CLI for auth-aware query handling. |
159-
| [Error Handling](/docs/server/error-handling) | Throw `CRPCError` with codes like `UNAUTHORIZED`, `NOT_FOUND`, `BAD_REQUEST`. |
160-
| [Server-Side Calls](/docs/server/server-side-calls) | Call procedures from server with `createCallerFactory`. RSC data fetching. |
161-
| [Scheduling](/docs/server/scheduling) | Run cron jobs and one-time background work with Convex scheduler APIs. |
162-
163-
### Plugins
164-
165-
| Page | When to Use |
166-
|------|-------------|
167-
| [Plugins](/docs/plugins) | Discover cross-cutting features that span schema, runtime, and client DX. |
168-
| [Rate Limiting](/docs/plugins/ratelimit) | Add token bucket and fixed/sliding window rate limiting with `kitcn/ratelimit`. |
169-
170-
### Database
171-
172-
| Page | When to Use |
173-
|------|-------------|
174-
| [ORM](/docs/orm) | Drizzle-style schema, queries, mutations, RLS, runtime constraints via `ctx.orm`. |
175-
| [Triggers](/docs/orm/schema/triggers) | Automatic side effects on insert/update/delete with schema triggers. |
176-
| [Aggregates](/docs/orm/queries/aggregates) | Scalar metrics (`count`, `aggregate`) and ranked aggregate runtime. |
177-
178-
### React (Client)
179-
180-
| Page | When to Use |
181-
|------|-------------|
182-
| [React Setup](/docs/react) | Configure providers: `QueryClientProvider`, `CRPCProvider`. Singleton helpers. |
183-
| [Queries](/docs/react/queries) | `useQuery` with `crpc.path.queryOptions()`. Real-time updates, `skipToken` for conditional queries. |
184-
| [Mutations](/docs/react/mutations) | `useMutation` with `crpc.path.mutationOptions()`. Toast patterns, optimistic updates. |
185-
| [Infinite Queries](/docs/react/infinite-queries) | `useInfiniteQuery` with `crpc.path.infiniteQueryOptions()`. Cursor-based pagination. |
186-
| [Type Inference](/docs/react/infer-types) | `inferApiInputs`, `inferApiOutputs` for tRPC-style type extraction. |
187-
| [Error Handling](/docs/react/error-handling) | Handle `CRPCClientError` on client. Error boundaries, toast notifications. |
188-
189-
### Next.js
190-
191-
| Page | When to Use |
192-
|------|-------------|
193-
| [Next.js Setup](/docs/nextjs) | Configure `convexBetterAuth` for RSC. Server caller factory, JWT caching. |
194-
| [RSC](/docs/nextjs/rsc) | Server components with `prefetch`, `preloadQuery`, `HydrateClient`. SSR data fetching. |
195-
196-
### Auth (Better Auth)
197-
198-
| Page | When to Use |
199-
|------|-------------|
200-
| [Auth Overview](/docs/auth) | Architecture overview. When to use Better Auth vs other auth solutions. |
201-
| [Auth Server](/docs/auth/server) | Complete Better Auth setup: schema, adapters, HTTP routes, helpers. |
202-
| [Auth Client](/docs/auth/client) | `useAuth`, `Authenticated`/`Unauthenticated` components. |
203-
204-
### Reference
205-
206-
| Page | When to Use |
207-
|------|-------------|
208-
| [CLI Backend](/docs/cli/backend) | `kitcn dev` for codegen. Procedure metadata generation. |
209-
| [Migrations](/docs/migrations/convex) | Migration hub with paths for Core, ORM, and Auth. |
210-
| [Comparison](/docs/comparison/convex) | Compare with tRPC, Convex hooks, other patterns. |
211-
212-
### Common Workflows
213-
214-
**New project setup:**
215-
1. [Quickstart](/docs/quickstart) → basic setup
216-
2. [CLI Registry](/docs/cli/registry) → use `kitcn init` for scaffolding or adoption, and `kitcn add` for feature layers
217-
3. [Concepts](/docs/concepts) → understand folder structure
218-
219-
**Add authentication:**
220-
1. [Auth Server](/docs/auth/server) → configure Better Auth
221-
2. [Auth Client](/docs/auth/client) → use auth in components
222-
3. [Middlewares](/docs/server/middlewares) → protect procedures
223-
224-
**Add database features:**
225-
1. [ORM](/docs/orm) → schema + queries via `ctx.orm`
226-
2. [Triggers](/docs/orm/schema/triggers) → automatic side effects
227-
3. [Aggregates](/docs/orm/queries/aggregates) → counts and sums
228-
229-
**Server components (RSC):**
230-
1. [Next.js Setup](/docs/nextjs) → configure caller
231-
2. [RSC](/docs/nextjs/rsc) → prefetch and hydrate

0 commit comments

Comments
 (0)