create-chaaskit 0.1.0

package/dist/templates/docs/development.md

@@ -0,0 +1,411 @@
+# Development
+
+This guide covers the development workflow for ChaasKit projects.
+
+## Starting Development
+
+```bash
+# In your project directory
+pnpm dev
+```
+
+This starts the React Router v7 dev server with HMR at `http://localhost:5173`, which proxies API requests to the Express backend at `http://localhost:3000`.
+
+---
+
+## Project Structure
+
+```
+my-app/
+├── app/
+│   ├── routes/                    # React Router v7 routes
+│   │   ├── _index.tsx             # Landing page (/)
+│   │   ├── login.tsx              # Login page (/login)
+│   │   ├── register.tsx           # Registration (/register)
+│   │   ├── chat._index.tsx        # Main chat (/chat)
+│   │   ├── chat.thread.$threadId.tsx  # Thread view
+│   │   ├── chat.documents.tsx     # Documents (/chat/documents)
+│   │   ├── chat.api-keys.tsx      # API Keys (/chat/api-keys)
+│   │   └── ...
+│   ├── components/                # Client wrapper components
+│   │   ├── ChatClient.tsx         # Chat page client wrapper
+│   │   └── ClientOnly.tsx         # SSR boundary component
+│   ├── root.tsx                   # HTML shell, theme, providers
+│   ├── routes.ts                  # Route configuration
+│   ├── entry.client.tsx           # Client hydration
+│   └── entry.server.tsx           # Server rendering
+├── config/
+│   └── app.config.ts              # Application configuration
+├── extensions/
+│   ├── agents/                    # Custom AI agents
+│   ├── payment-plans/             # Custom pricing plans
+│   └── pages/                     # Custom frontend pages
+├── prisma/
+│   └── schema/
+│       ├── base.prisma            # ChaasKit models (synced)
+│       └── custom.prisma          # Your custom models
+├── public/
+│   ├── logo.svg                   # Your logo
+│   └── favicon.svg                # Favicon
+├── .env                           # Environment variables
+├── server.js                      # Production server
+├── vite.config.ts                 # Vite configuration
+├── react-router.config.ts         # React Router configuration
+└── package.json
+```
+
+---
+
+## Commands
+
+### Development
+
+```bash
+pnpm dev          # Start dev server with HMR
+pnpm build        # Build for production
+pnpm typecheck    # Run TypeScript checks
+pnpm start        # Start production server
+```
+
+### Database
+
+```bash
+pnpm db:generate  # Generate Prisma client
+pnpm db:push      # Push schema changes (dev)
+pnpm db:migrate   # Create and run migrations (prod)
+pnpm db:studio    # Open Prisma Studio
+pnpm db:sync      # Sync base.prisma from @chaaskit/db
+```
+
+---
+
+## Common Tasks
+
+### Customize Configuration
+
+Edit `config/app.config.ts`:
+
+```typescript
+import type { AppConfig } from '@chaaskit/shared';
+
+export const config: AppConfig = {
+  app: {
+    name: 'My App',
+    description: 'My AI chat application',
+    url: 'http://localhost:5173',
+    basePath: '/chat',
+  },
+  agent: {
+    type: 'built-in',
+    provider: 'anthropic',
+    model: 'claude-sonnet-4-20250514',
+    systemPrompt: 'You are a helpful assistant.',
+  },
+  // ... other options
+};
+```
+
+The server automatically reloads when config changes.
+
+### Add a Custom Agent
+
+Create `extensions/agents/my-agent.ts`:
+
+```typescript
+import { BaseAgent, registry } from '@chaaskit/server';
+
+export class MyAgent extends BaseAgent {
+  async *chat(messages, options) {
+    yield { type: 'text', content: 'Hello!' };
+    yield { type: 'done' };
+  }
+}
+
+registry.register('agent', 'my-agent', MyAgent);
+```
+
+Then reference it in config:
+
+```typescript
+agent: {
+  type: 'custom',
+  agentId: 'my-agent',
+}
+```
+
+### Add a Custom Route
+
+Create a new route file in `app/routes/`. React Router v7 uses file-based routing:
+
+```tsx
+// app/routes/chat.my-page.tsx
+// This creates a route at /chat/my-page
+
+import { ChatProviders } from '@chaaskit/client';
+
+export default function MyPage() {
+  return (
+    <ChatProviders>
+      <div className="min-h-screen bg-background p-8">
+        <h1 className="text-2xl font-bold text-text-primary">
+          My Custom Page
+        </h1>
+      </div>
+    </ChatProviders>
+  );
+}
+```
+
+For pages that need data loading:
+
+```tsx
+// app/routes/chat.stats.tsx
+import type { Route } from './+types/chat.stats';
+import { ChatProviders } from '@chaaskit/client';
+
+export async function loader({ request }: Route.LoaderArgs) {
+  // Server-side data loading
+  return { stats: { threads: 42 } };
+}
+
+export default function StatsPage({ loaderData }: Route.ComponentProps) {
+  return (
+    <ChatProviders>
+      <div className="p-8">
+        <h1>Stats</h1>
+        <p>Total threads: {loaderData.stats.threads}</p>
+      </div>
+    </ChatProviders>
+  );
+}
+```
+
+### Add a Custom Database Model
+
+1. Edit `prisma/schema/custom.prisma`:
+
+```prisma
+model MyModel {
+  id        String   @id @default(cuid())
+  name      String
+  userId    String
+  user      User     @relation(fields: [userId], references: [id])
+  createdAt DateTime @default(now())
+}
+```
+
+2. Apply changes:
+
+```bash
+pnpm db:push      # Development
+pnpm db:generate  # Regenerate client
+```
+
+3. Use in your code:
+
+```typescript
+import { db } from '@chaaskit/db';
+
+const items = await db.myModel.findMany({
+  where: { userId: user.id }
+});
+```
+
+---
+
+## Adding Custom API Routes
+
+Create a custom server entry point to add routes alongside ChaasKit's API.
+
+### Custom Server
+
+Create `src/server.ts`:
+
+```typescript
+import { createApp } from '@chaaskit/server';
+import { Router } from 'express';
+import { config } from '../config/app.config.js';
+
+async function start() {
+  const app = await createApp({ config });
+
+  // Add custom routes
+  const customRouter = Router();
+
+  customRouter.get('/api/custom/hello', (req, res) => {
+    res.json({ message: 'Hello!' });
+  });
+
+  app.use(customRouter);
+
+  const port = process.env.PORT || 3000;
+  app.listen(port, () => {
+    console.log(`Server running on port ${port}`);
+  });
+}
+
+start().catch(console.error);
+```
+
+### Using Auth Middleware
+
+```typescript
+import { requireAuth, optionalAuth } from '@chaaskit/server';
+
+// Protected route
+customRouter.get('/api/custom/profile', requireAuth, (req, res) => {
+  res.json({
+    userId: req.user!.id,
+    email: req.user!.email,
+  });
+});
+
+// Optional auth
+customRouter.get('/api/custom/public', optionalAuth, (req, res) => {
+  if (req.user) {
+    res.json({ greeting: `Hello, ${req.user.email}!` });
+  } else {
+    res.json({ greeting: 'Hello, guest!' });
+  }
+});
+```
+
+### Accessing the Database
+
+```typescript
+import { db } from '@chaaskit/db';
+import { requireAuth } from '@chaaskit/server';
+
+customRouter.get('/api/custom/stats', requireAuth, async (req, res) => {
+  const threadCount = await db.thread.count({
+    where: { userId: req.user!.id },
+  });
+
+  res.json({ threads: threadCount });
+});
+```
+
+---
+
+## Route Naming Convention
+
+React Router v7 uses dot notation for nested routes:
+
+| File | URL Path |
+|------|----------|
+| `app/routes/_index.tsx` | `/` |
+| `app/routes/login.tsx` | `/login` |
+| `app/routes/chat._index.tsx` | `/chat` |
+| `app/routes/chat.thread.$threadId.tsx` | `/chat/thread/:threadId` |
+| `app/routes/chat.documents.tsx` | `/chat/documents` |
+| `app/routes/shared.$shareId.tsx` | `/shared/:shareId` |
+
+The `$` prefix creates dynamic segments. The `_index` suffix creates index routes.
+
+---
+
+## Client-Side Navigation
+
+Use `useAppPath` for navigation that respects `basePath`:
+
+```tsx
+import { useAppPath } from '@chaaskit/client';
+import { Link } from 'react-router';
+
+function MyComponent() {
+  const appPath = useAppPath();
+
+  return (
+    <Link to={appPath('/documents')}>
+      Go to Documents
+    </Link>
+  );
+}
+```
+
+This ensures links work correctly whether `basePath` is `/` or `/chat`.
+
+---
+
+## Debugging
+
+### Server Logs
+
+Watch the terminal for:
+- Request logs: `GET /api/threads 200 15ms`
+- Config loading: `[Config] Loaded from ./config/app.config.ts`
+- Extension loading: `[Extensions] Loaded: extensions/agents/my-agent.ts`
+- Errors with stack traces
+
+### Database Inspection
+
+```bash
+pnpm db:studio  # Opens at http://localhost:5555
+```
+
+### Frontend DevTools
+
+- React DevTools for component inspection
+- Network tab for API requests
+- Console for errors
+
+---
+
+## Type Checking
+
+```bash
+pnpm typecheck
+```
+
+This runs TypeScript across all files to catch type errors.
+
+---
+
+## Network Access
+
+To access from other devices on your network:
+
+1. The dev server exposes on `0.0.0.0:5173` via the `--host` flag
+2. Add allowed hostnames to `vite.config.ts`:
+
+```typescript
+server: {
+  host: true,
+  allowedHosts: ['my-machine.local', '192.168.1.100'],
+}
+```
+
+---
+
+## Monorepo Development
+
+If you're contributing to ChaasKit itself, see the main repository's CLAUDE.md for monorepo-specific instructions.
+
+### Building Packages
+
+```bash
+pnpm build
+```
+
+### Linking for Local Development
+
+```bash
+# In the chaaskit monorepo
+pnpm build
+pnpm -r exec pnpm link --global
+
+# In your test project
+pnpm link --global @chaaskit/server @chaaskit/client @chaaskit/db @chaaskit/shared
+```
+
+### Testing the CLI
+
+```bash
+# Build and run directly
+cd packages/create-chaaskit
+pnpm build
+node dist/index.js create my-test-app --skip-install
+
+# Or use the test script
+./scripts/create-test-project.sh
+```

package/dist/templates/docs/documents.md

@@ -0,0 +1,293 @@
+# Mentionable Documents
+
+Mentionable documents allow users to reference stored content in chat using @-mention syntax. Documents are organized by scope (personal, team, or project) and can be automatically injected into the AI context or accessed via tools.
+
+File attachments in chat also use this system - when you attach a file to a message, it's uploaded as a document and automatically @-mentioned.
+
+## Quick Start
+
+1. Enable documents in your config:
+
+```typescript
+// config/app.config.ts
+documents: {
+  enabled: true,
+  storage: { provider: 'database' },
+  maxFileSizeMB: 10,
+  hybridThreshold: 1000,
+  acceptedTypes: ['text/plain', 'text/markdown', 'text/x-markdown', 'text/csv', 'application/json'],
+}
+```
+
+2. Create or upload documents via the Documents page (`/documents`)
+3. Reference documents in chat using `@my/document-name` syntax
+
+## Mention Syntax
+
+Documents are referenced using scoped paths:
+
+| Scope | Syntax | Example |
+|-------|--------|---------|
+| Personal | `@my/<name>` | `@my/api-guidelines` |
+| Team | `@team/<slug>/<name>` | `@team/engineering/style-guide` |
+| Project | `@project/<slug>/<name>` | `@project/acme/requirements` |
+
+Document names should be lowercase with hyphens (e.g., `api-guidelines`, `meeting-notes`).
+
+## How It Works
+
+### Hybrid Access Model
+
+Documents use a hybrid approach based on size:
+
+- **Small documents** (under `hybridThreshold` chars): Content is automatically injected into the AI context when mentioned
+- **Large documents** (over threshold): AI receives tools to read, search, and list document contents
+
+This balances context efficiency with full access to large documents.
+
+### Document Scopes
+
+| Scope | Access | Use Case |
+|-------|--------|----------|
+| **Personal** (`my`) | Only the owner | Personal notes, private references |
+| **Team** | All team members | Shared team knowledge, guidelines |
+| **Project** | Project participants | Project-specific documentation |
+
+## Configuration
+
+```typescript
+interface DocumentsConfig {
+  enabled: boolean;
+  storage: {
+    provider: 'database' | 'filesystem' | 's3';
+    filesystem?: { basePath: string };
+    s3?: { bucket: string; region: string; endpoint?: string };
+  };
+  maxFileSizeMB: number;
+  hybridThreshold: number;  // Character count threshold for context injection
+  acceptedTypes: string[];  // MIME types
+}
+```
+
+### Storage Providers
+
+**Database (default)** - Content stored in the Document table. Best for small to medium documents.
+
+```typescript
+storage: { provider: 'database' }
+```
+
+**Filesystem** - Content stored on disk. Good for larger files or when you need direct file access.
+
+```typescript
+storage: {
+  provider: 'filesystem',
+  filesystem: { basePath: './uploads/documents' }
+}
+```
+
+**S3** - Content stored in S3-compatible storage. Best for production deployments.
+
+```typescript
+storage: {
+  provider: 's3',
+  s3: {
+    bucket: 'my-documents-bucket',
+    region: 'us-east-1',
+    endpoint: 'https://s3.amazonaws.com'  // Optional, for S3-compatible services
+  }
+}
+```
+
+### Accepted File Types
+
+The `acceptedTypes` array specifies which MIME types can be uploaded. Default types:
+
+```typescript
+acceptedTypes: [
+  'text/plain',       // .txt files
+  'text/markdown',    // .md files
+  'text/x-markdown',  // .md files (alternate MIME type)
+  'text/csv',         // .csv files
+  'application/json', // .json files
+]
+```
+
+### Hybrid Threshold
+
+The `hybridThreshold` controls when documents are injected vs accessed via tools:
+
+```typescript
+hybridThreshold: 1000  // Characters
+```
+
+- Documents with `charCount <= 1000`: Injected directly into AI context
+- Documents with `charCount > 1000`: AI uses tools to read content
+
+Adjust based on your typical document sizes and context budget.
+
+## AI Tools
+
+When large documents are mentioned, the AI receives these tools:
+
+### `list_documents`
+Lists available documents, optionally filtered by query or scope.
+
+### `read_document`
+Reads content from a document with pagination support.
+
+```typescript
+{
+  path: '@my/api-guidelines',
+  offset: 0,   // Start line
+  limit: 100   // Max lines
+}
+```
+
+### `search_in_document`
+Searches for text within a document.
+
+```typescript
+{
+  path: '@my/api-guidelines',
+  query: 'authentication',
+  context_lines: 3
+}
+```
+
+### `save_document`
+Saves AI-generated content as a new document.
+
+```typescript
+{
+  name: 'meeting-summary',
+  content: '...',
+  scope: 'my'  // or 'team', 'project'
+}
+```
+
+## API Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/documents` | GET | List documents |
+| `/api/documents` | POST | Create text document |
+| `/api/documents/upload` | POST | Upload file |
+| `/api/documents/:id` | GET | Get document metadata |
+| `/api/documents/:id` | PATCH | Update document |
+| `/api/documents/:id` | DELETE | Archive document |
+| `/api/documents/:id/content` | GET | Get document content |
+| `/api/mentions/search` | GET | Search mentionable documents |
+| `/api/mentions/resolve` | POST | Resolve mention paths |
+
+## File Attachments in Chat
+
+The chat file attachment button (paperclip icon) uploads files as documents and automatically @-mentions them in your message. This provides a unified experience:
+
+1. Click the attachment icon in the chat input
+2. Select one or more files
+3. Files are uploaded as documents to your personal scope (or team/project if selected)
+4. @-mentions are automatically appended to your message
+
+For example, attaching `report.csv` will:
+- Create a document at `@my/report`
+- Append `@my/report` to your message
+- The AI can then access the document content via the hybrid system
+
+**Note**: The attachment button only appears when documents are enabled in configuration.
+
+## Frontend Components
+
+### Documents Page
+
+Access via `/documents` or the sidebar link. Features:
+
+- Create text documents inline
+- Upload files (drag & drop supported)
+- View, edit, and delete documents
+- Filter by scope and search by name
+
+### Mention Input
+
+When typing in chat:
+
+1. Type `@` to trigger the mention dropdown
+2. Continue typing to filter documents
+3. Use arrow keys to navigate, Enter to select
+4. Selected document path is inserted into the message
+
+### Mention Chips
+
+Document mentions in messages render as styled chips showing:
+
+- Scope icon (user/team/project)
+- Document name
+- Full path on hover
+
+## Database Schema
+
+```prisma
+model Document {
+  id          String    @id @default(cuid())
+  name        String
+  content     String?   @db.Text
+  storageKey  String?
+  mimeType    String    @default("text/plain")
+  fileSize    Int       @default(0)
+  charCount   Int       @default(0)
+
+  userId      String
+  user        User      @relation(...)
+  teamId      String?
+  team        Team?     @relation(...)
+  projectId   String?
+  project     Project?  @relation(...)
+
+  createdAt   DateTime  @default(now())
+  updatedAt   DateTime  @updatedAt
+  archivedAt  DateTime?
+
+  @@unique([userId, name, teamId, projectId])
+}
+```
+
+## Text Extraction
+
+Documents are processed to extract plain text for AI consumption:
+
+| File Type | Handling |
+|-----------|----------|
+| Plain text (.txt) | Passthrough |
+| Markdown (.md) | Passthrough |
+| CSV (.csv) | Converted to readable table format |
+| JSON (.json) | Passthrough |
+
+The extractor system is extensible. Future versions may support PDF, DOCX, and XLSX.
+
+## Best Practices
+
+1. **Use descriptive names**: `api-authentication-guide` is better than `doc1`
+2. **Keep documents focused**: One topic per document improves mention relevance
+3. **Set appropriate scope**: Use team/project scope for shared knowledge
+4. **Consider document size**: Very large documents may be slow to search
+5. **Update regularly**: Keep referenced documents current
+
+## Troubleshooting
+
+### Documents not appearing in mentions
+
+- Verify documents feature is enabled in config
+- Check that the document isn't archived
+- Ensure you have access to the document's scope
+
+### Upload fails
+
+- Check file size against `maxFileSizeMB`
+- Verify MIME type is in `acceptedTypes`
+- Check server logs for detailed errors
+
+### AI not reading document content
+
+- For large documents, ensure the AI is using the `read_document` tool
+- Check that document tools are registered (visible in tool calls)
+- Verify the document path is correct in the mention