Bootstrap agent-ready docs and permissions (D-036)
Root AGENTS.md is now the single source of truth for coding agents; CLAUDE.md, GEMINI.md and docs/CLAUDE.md are pointers. The product spec moves from docs/CLAUDE.md to PRODUCT.md, DESIGN.md records the shipped visual system, and docs/PERMISSIONS.md defines agent permission tiers rendered to .claude/, .codex/ and .gemini/. Adds docs/specs/ and docs/plans/, logs issues noticed (not fixed) in WorkBreakdown.md. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Lucas WintherandClaude Opus 5.5 committed
1 parent
c1b710cb23
commit
0ece4b3a2a
18 files changed
+423
-130
No files matched your search
+9
-126
@@ -1,129 +1,12 @@
|
||||
# CLAUDE.md — Read this first, every session
|
||||
# docs/CLAUDE.md
|
||||
|
||||
This is the single source of truth for any agent working in this repo. If anything
|
||||
you're told conflicts with this file, this file wins.
|
||||
**`AGENTS.md` (repo root) is the single source of truth for agents in this repository.** Read
|
||||
`../AGENTS.md` and follow it exactly. This file contains no rules of its own.
|
||||
|
||||
## 1. What we are building
|
||||
This file used to hold the product spec and the Bun toolchain rules (it was the original `bun init`
|
||||
CLAUDE.md, extended). Its content now lives in:
|
||||
- Product spec ("what we are building") → `PRODUCT.md`
|
||||
- Bun toolchain and API rules → `AGENTS.md` § Rules
|
||||
- Bun API reference → `node_modules/bun-types/docs/`
|
||||
|
||||
A browser-first speech-to-text web app powered by OpenAI Whisper, running through
|
||||
[Transformers.js](https://github.com/huggingface/transformers) (`@huggingface/transformers`).
|
||||
|
||||
**Anonymous users (no login) can:**
|
||||
- Run Whisper models fully in the browser (no data leaves the device).
|
||||
- Choose which Whisper model to use (tiny → large, English-only and multilingual, quantized variants).
|
||||
- Keep working when the network — or our own server — is offline (installable PWA + cached model weights).
|
||||
- Accelerate inference with WebNN or WebGPU (auto-selected in that order, D-017), falling back to WASM automatically.
|
||||
- Transcribe from an uploaded audio/video file.
|
||||
|
||||
**Logged-in users (Passport.js) get all of the above, plus:**
|
||||
- A toggle to choose where inference runs: **their own device** (browser engine) or **the server** the app is deployed on (server engine).
|
||||
- The server engine MUST use [faster-whisper](https://github.com/SYSTRAN/faster-whisper) (CTranslate2) for inference — not Transformers.js (see Decisions.md D-013). faster-whisper cannot run in a browser (no WASM build of CTranslate2), so the browser engine stays on Transformers.js.
|
||||
|
||||
## 2 How to run things
|
||||
|
||||
|
||||
Default to using Bun instead of Node.js.
|
||||
|
||||
- Use `bun <file>` instead of `node <file>` or `ts-node <file>`
|
||||
- Use `bun test` instead of `jest` or `vitest`
|
||||
- Use `bun build <file.html|file.ts|file.css>` instead of `webpack` or `esbuild`
|
||||
- Use `bun install` instead of `npm install` or `yarn install` or `pnpm install`
|
||||
- Use `bun run <script>` instead of `npm run <script>` or `yarn run <script>` or `pnpm run <script>`
|
||||
- Use `bunx <package> <command>` instead of `npx <package> <command>`
|
||||
- Bun automatically loads .env, so don't use dotenv.
|
||||
|
||||
## APIs
|
||||
|
||||
- `Bun.serve()` supports WebSockets, HTTPS, and routes. Don't use `express`.
|
||||
- `bun:sqlite` for SQLite. Don't use `better-sqlite3`.
|
||||
- `Bun.redis` for Redis. Don't use `ioredis`.
|
||||
- `Bun.sql` for Postgres. Don't use `pg` or `postgres.js`.
|
||||
- `WebSocket` is built-in. Don't use `ws`.
|
||||
- Prefer `Bun.file` over `node:fs`'s readFile/writeFile
|
||||
- Bun.$`ls` instead of execa.
|
||||
|
||||
## Testing
|
||||
|
||||
Use `bun test` to run tests.
|
||||
|
||||
```ts#index.test.ts
|
||||
import { test, expect } from "bun:test";
|
||||
|
||||
test("hello world", () => {
|
||||
expect(1).toBe(1);
|
||||
});
|
||||
```
|
||||
|
||||
## Frontend
|
||||
|
||||
Use HTML imports with `Bun.serve()`. Don't use `vite`. HTML imports fully support React, CSS, Tailwind.
|
||||
|
||||
Server:
|
||||
|
||||
```ts#index.ts
|
||||
import index from "./index.html"
|
||||
|
||||
Bun.serve({
|
||||
routes: {
|
||||
"/": index,
|
||||
"/api/users/:id": {
|
||||
GET: (req) => {
|
||||
return new Response(JSON.stringify({ id: req.params.id }));
|
||||
},
|
||||
},
|
||||
},
|
||||
// optional websocket support
|
||||
websocket: {
|
||||
open: (ws) => {
|
||||
ws.send("Hello, world!");
|
||||
},
|
||||
message: (ws, message) => {
|
||||
ws.send(message);
|
||||
},
|
||||
close: (ws) => {
|
||||
// handle close
|
||||
}
|
||||
},
|
||||
development: {
|
||||
hmr: true,
|
||||
console: true,
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
HTML files can import .tsx, .jsx or .js files directly and Bun's bundler will transpile & bundle automatically. `<link>` tags can point to stylesheets and Bun's CSS bundler will bundle.
|
||||
|
||||
```html#index.html
|
||||
<html>
|
||||
<body>
|
||||
<h1>Hello, world!</h1>
|
||||
<script type="module" src="./frontend.tsx"></script>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
With the following `frontend.tsx`:
|
||||
|
||||
```tsx#frontend.tsx
|
||||
import React from "react";
|
||||
import { createRoot } from "react-dom/client";
|
||||
|
||||
// import .css files directly and it works
|
||||
import './index.css';
|
||||
|
||||
const root = createRoot(document.body);
|
||||
|
||||
export default function Frontend() {
|
||||
return <h1>Hello, world!</h1>;
|
||||
}
|
||||
|
||||
root.render(<Frontend />);
|
||||
```
|
||||
|
||||
Then, run index.ts
|
||||
|
||||
```sh
|
||||
bun --hot ./index.ts
|
||||
```
|
||||
|
||||
For more information, read the Bun API docs in `node_modules/bun-types/docs/**.mdx`.
|
||||
See Decisions.md D-036.
|
||||
Reference in new issue
Block a user