feat(prompt,readme): load project-instruction file + corrected feature list

- buildProjectFilesAddendum: looks for AGENTS.md → CLAUDE.md → CODEX.md
  → .cursorrules at the project root (first match wins), injects its
  content into the system prompt under a "Project instructions" header.
  64KB cap with a truncation notice. createAgent layers this between
  the static system prompt and the MEMORY.md addendum.

- README rewritten:
    - Honest feature list (no more demoscene boot screen — that was Go
      v1 only; project awareness is now actually wired up)
    - Codebase.design free tier explained as 10-turn taste, not
      unlimited
    - Paid account section explains what the subscription unlocks
    - 95 lines total

Author: halfaipg

README.md

@@ -15,11 +15,7 @@
 </p>
 
 <p align="center">
-  <a href="https://github.com/earendil-works/pi">
-    <img src="https://pi.dev/logo-auto.svg" alt="Powered by pi" width="20" align="absmiddle" />
-    &nbsp;<strong>Powered by <a href="https://github.com/earendil-works/pi">pi</a></strong>
-  </a>
-  &nbsp;·&nbsp;
+  <strong>Powered by <a href="https://github.com/earendil-works/pi">pi</a></strong> &nbsp;·&nbsp;
   <em>The agent loop, provider adapters, and session protocol come from <a href="https://github.com/earendil-works/pi">pi-mono</a>.</em>
 </p>
 
@@ -35,13 +31,18 @@ ANTHROPIC_API_KEY=sk-ant-... codebase
 OPENAI_API_KEY=sk-... codebase
 ```
 
-**Or sign in once via [codebase.design](https://codebase.design)** and try open-weight models instantly with no key setup — MiniMax, Qwen, Llama, and others routed through our inference proxy. One auth, every model.
+**Sign in to [codebase.design](https://codebase.design) and skip key wrangling.** One auth, every model.
+
+- **Free tier** — try open-weight models (MiniMax, Qwen, Llama, etc.) with a **10-turn taste** so you can kick the tires before paying anyone for anything. No API keys to set up.
+- **Paid account** — uncaps the open-weights, adds the frontier models (Claude Opus / Sonnet, GPT-5, …), higher rate limits, and longer context windows. One subscription replaces N provider bills.
 
 ```sh
 codebase auth login
 codebase
 ```
 
+Switch between models any time with `/model` (interactive picker) or `/model <id>`.
+
 ## Install
 
 Requires **Node.js ≥ 20**.
@@ -67,28 +68,42 @@ codebase
 Type. Hit enter. The agent reads files, runs tests, edits code, and shows you what it did. Slash `/help` for the rest.
 
 A few things worth knowing:
-- `/model` — pick a model interactively (live list of what your account can hit)
+
+- `/model` — pick a model interactively, live list of what your account can hit
 - `/plan` — Q&A before the agent touches anything
 - `!cmd` — run a shell command without spending a turn
 - `@path` — pin a file into the next prompt
 - `\<Enter>` — multi-line input
+- **Type while the agent is working** — your prompt queues, fires when the current turn ends (`Ctrl-C` while busy clears the queue along with the turn)
 - **Ctrl-C** stops the current turn, twice fast exits
 
+## What it does
+
+- **Streaming responses.** Real-time token output, coalesced to 60 fps so the TUI doesn't thrash.
+- **Multi-turn agentic loop.** Tool call → result → next turn, automatically.
+- **Parallel tool execution.** Read-only tools (grep, glob, read, git status…) run concurrently within a turn.
+- **Project awareness.** Auto-loads `AGENTS.md`, `CLAUDE.md`, `CODEX.md`, or `.cursorrules` from the project root into the system prompt.
+- **Conversation compaction.** Long sessions automatically summarize older turns to stay under the context window.
+- **Session persistence.** Auto-resume from where you left off; `--new` for a clean slate.
+- **Plan mode.** A cheap-model Q&A pass surfaces the right plan before the expensive agent starts editing.
+- **Intent routing.** Chit-chat doesn't burn a full agent turn; complex asks roll into plan mode automatically.
+- **Subagent dispatch.** Spawn isolated research agents that keep their tool noise out of your main context.
+
 ## Builder-focused defaults
 
 - **Any LLM**, not just Anthropic. Provider choice is config.
-- **45+ tools** that all live behind one small interface — adding one is mechanical.
+- **45+ tools** behind one small interface — adding one is mechanical.
 - **Effect-based permissions** instead of tool-name allowlists.
-- **Single immutable state** driven by a typed reducer — the whole UI is one render of one value.
+- **Single immutable state** driven by a typed reducer — the UI is one render of one value.
 - **Multi-process safe OAuth** with lockfile-coordinated token refresh — run 10 instances of codebase at once and they share a single refresh per hour.
-- **Plain `npm i -g`**, single binary, no bundler lock-in.
+- **Plain `npm i -g`**, no bundler lock-in.
 
 ## More
 
 - [`.settings/`](.settings/) — orientation: tenets, architecture, extending, testing
 - [`CLAUDE.md`](CLAUDE.md) — quick reference for AI agents working in this repo
 - [`docs/MIGRATION_v1_to_v2.md`](docs/MIGRATION_v1_to_v2.md) — upgrading from the Go v1 binary
-- [`/help` in the CLI](#) — every slash command and shortcut
+- `/help` inside the CLI — every slash command and shortcut
 
 ## License
 

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "codebase-cli",
-	"version": "2.0.0-pre.51",
+	"version": "2.0.0-pre.52",
 	"description": "Codebase CLI — a TypeScript coding agent on the pi-mono runtime. OAuth-aware, any LLM provider, single install.",
 	"keywords": [
 		"ai",

src/agent/agent.ts

@@ -22,6 +22,7 @@ import { TaskStore } from "../tools/task-store.js";
 import type { ToolContext } from "../tools/types.js";
 import { UserQueryStore } from "../user-queries/store.js";
 import { type ResolvedConfig, resolveConfig } from "./config.js";
+import { buildProjectFilesAddendum } from "./project-files.js";
 import { buildSystemPrompt } from "./system-prompt.js";
 
 const WRITE_TOOL_NAMES: ReadonlySet<string> = new Set(["write_file", "edit_file", "multi_edit", "notebook_edit"]);
@@ -185,7 +186,11 @@ export function createAgent(opts: CreateAgentOptions = {}): AgentBundle {
 
 	// MEMORY.md gets concatenated onto the system prompt at agent creation.
 	// Reload-after-save is a Phase 11 polish item.
-	const fullSystemPrompt = systemPrompt + buildMemoryAddendum(memory);
+	// Project-instruction file (first of AGENTS.md / CLAUDE.md / CODEX.md /
+	// .cursorrules) gets pinned to the prompt so the agent sees the
+	// project's conventions on every turn. Memory addendum is appended
+	// after — it's the user's accumulated long-term notes.
+	const fullSystemPrompt = systemPrompt + buildProjectFilesAddendum(cwd) + buildMemoryAddendum(memory);
 
 	const agent = new Agent({
 		initialState: {

src/agent/project-files.test.ts

@@ -0,0 +1,73 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { buildProjectFilesAddendum } from "./project-files.js";
+
+describe("buildProjectFilesAddendum", () => {
+	let cwd: string;
+
+	beforeEach(() => {
+		cwd = mkdtempSync(join(tmpdir(), "project-files-"));
+	});
+
+	afterEach(() => {
+		rmSync(cwd, { recursive: true, force: true });
+	});
+
+	it("returns empty string when no recognized file exists", () => {
+		expect(buildProjectFilesAddendum(cwd)).toBe("");
+	});
+
+	it("loads CLAUDE.md when present", () => {
+		writeFileSync(join(cwd, "CLAUDE.md"), "# Project Rules\n\nNo cowboy coding.");
+		const out = buildProjectFilesAddendum(cwd);
+		expect(out).toContain("# Project instructions (CLAUDE.md)");
+		expect(out).toContain("No cowboy coding");
+	});
+
+	it("loads AGENTS.md when present and prefers it over CLAUDE.md (first match wins)", () => {
+		writeFileSync(join(cwd, "AGENTS.md"), "AGENTS RULES");
+		writeFileSync(join(cwd, "CLAUDE.md"), "CLAUDE RULES");
+		const out = buildProjectFilesAddendum(cwd);
+		expect(out).toContain("# Project instructions (AGENTS.md)");
+		expect(out).toContain("AGENTS RULES");
+		expect(out).not.toContain("CLAUDE RULES");
+	});
+
+	it("loads CODEX.md when neither AGENTS.md nor CLAUDE.md exists", () => {
+		writeFileSync(join(cwd, "CODEX.md"), "CODEX RULES");
+		const out = buildProjectFilesAddendum(cwd);
+		expect(out).toContain("# Project instructions (CODEX.md)");
+		expect(out).toContain("CODEX RULES");
+	});
+
+	it("loads .cursorrules as a last resort", () => {
+		writeFileSync(join(cwd, ".cursorrules"), "CURSOR RULES");
+		const out = buildProjectFilesAddendum(cwd);
+		expect(out).toContain("# Project instructions (.cursorrules)");
+		expect(out).toContain("CURSOR RULES");
+	});
+
+	it("truncates content past the byte cap with a notice", () => {
+		const huge = "x".repeat(70 * 1024); // 70KB > 64KB cap
+		writeFileSync(join(cwd, "CLAUDE.md"), huge);
+		const out = buildProjectFilesAddendum(cwd);
+		expect(out).toContain("…truncated");
+		expect(out).toContain("CLAUDE.md");
+		expect(out.length).toBeLessThan(huge.length);
+	});
+
+	it("ignores a directory named CLAUDE.md (not a regular file)", () => {
+		mkdirSync(join(cwd, "CLAUDE.md"));
+		expect(buildProjectFilesAddendum(cwd)).toBe("");
+	});
+
+	it("trims surrounding whitespace from the file content", () => {
+		writeFileSync(join(cwd, "CLAUDE.md"), "\n\n   rule one  \n\n");
+		const out = buildProjectFilesAddendum(cwd);
+		expect(out).toContain("rule one");
+		// Section structure intact, no leading/trailing spaces on the content body.
+		expect(out).toMatch(/\n\nrule one\n\n*$/);
+	});
+});

src/agent/project-files.ts

@@ -0,0 +1,49 @@
+import { readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Project-instruction files we look for at the cwd root. The first
+ * present file wins to avoid duplicate injection — a project that has
+ * both CLAUDE.md (for one IDE) and AGENTS.md (for another) shouldn't
+ * concatenate both into the prompt.
+ */
+const RECOGNIZED_FILES = ["AGENTS.md", "CLAUDE.md", "CODEX.md", ".cursorrules"] as const;
+
+/** Hard cap on the injected content. Anything beyond this is truncated
+ *  with a notice. Keeps a runaway CLAUDE.md from blowing the prompt. */
+const MAX_BYTES = 64 * 1024;
+
+/**
+ * Build the project-instructions system-prompt addendum. Reads the
+ * first recognized file at the cwd root (AGENTS.md / CLAUDE.md /
+ * CODEX.md / .cursorrules) and returns it wrapped in a labeled
+ * section. Returns "" when no file is present.
+ */
+export function buildProjectFilesAddendum(cwd: string): string {
+	for (const name of RECOGNIZED_FILES) {
+		const path = join(cwd, name);
+		try {
+			const stat = statSync(path);
+			if (!stat.isFile()) continue;
+			let content = readFileSync(path, "utf8");
+			let truncated = false;
+			if (Buffer.byteLength(content, "utf8") > MAX_BYTES) {
+				// Slice by bytes, then trim back to a char boundary by
+				// re-decoding. utf8 truncation can split a multibyte
+				// sequence; slicing the string and re-encoding is safer
+				// than buffer math here.
+				content = content.slice(0, MAX_BYTES);
+				while (Buffer.byteLength(content, "utf8") > MAX_BYTES) {
+					content = content.slice(0, -1);
+				}
+				truncated = true;
+			}
+			const header = `\n\n# Project instructions (${name})\n\n`;
+			const footer = truncated ? `\n\n(…truncated; full file at ${path})` : "";
+			return `${header}${content.trim()}${footer}\n`;
+		} catch {
+			// File missing or unreadable — move on to the next candidate.
+		}
+	}
+	return "";
+}