feat: scaffold a workspace README and a Project notes section in AGENTS file for user provided standards

.changeset/scaffold-workspace-readme.md

@@ -0,0 +1,5 @@
+---
+'create-tessera': patch
+---
+
+Scaffolded workspaces now include a human-facing `README.md` and a "Project notes" section in `AGENTS.md` where users add their own context for the agent.

.prettierignore

@@ -7,3 +7,4 @@ tests/.e2e-variants/**
 pnpm-lock.yaml
 CHANGELOG.md
 *.tsbuildinfo
+packages/create-tessera/templates/workspace/README.md

packages/create-tessera/templates/workspace/AGENTS.md

@@ -11,5 +11,20 @@ ships with the framework. Run `pnpm install`, then read it at
 
 **Open this workspace folder** (not an individual course) so this guide is in
 scope. Add a course with `pnpm tessera new <name>`; run a command against one with
-`pnpm tessera dev <name>` (or cd into its folder and run `pnpm exec tessera dev`). The guide always matches your
-installed `tessera-learn` version, so there's nothing to keep in sync here.
+`pnpm tessera dev <name>` (or cd into its folder and run `pnpm exec tessera dev`). The framework guide always
+matches your installed `tessera-learn` version, so there's nothing to keep in sync
+above this line.
+
+---
+
+## Project notes
+
+Add your own context for the agent here — it takes precedence over the framework
+guide above. For example:
+
+- **Audience** — who these courses are for (role, prior knowledge).
+- **Voice & tone** — how content should read.
+- **Brand & a11y** — colors, logos, contrast or reading-level requirements.
+- **Review** — SMEs or stakeholders who sign off, and any naming conventions.
+
+_(Delete the examples and write your own.)_

packages/create-tessera/templates/workspace/README.md

@@ -0,0 +1,37 @@
+# __PROJECT_NAME__
+
+> Edit this README to describe your course library.
+
+A [Tessera](https://www.npmjs.com/package/tessera-learn) workspace — many courses
+under `courses/`, with a shared design system in `shared/` (imported as `$shared`).
+
+## Quick start
+
+```bash
+pnpm install
+pnpm dev starter-course      # preview a course in the browser
+pnpm tessera new <name>      # add a course
+```
+
+## Commands
+
+Author:
+
+```bash
+pnpm tessera new <name>            # scaffold a new course
+pnpm tessera duplicate <src> <to>  # copy an existing course
+pnpm dev <course>                  # live preview
+```
+
+Ship:
+
+```bash
+pnpm validate <course>   # check structure & LMS rules
+pnpm a11y <course>       # accessibility audit
+pnpm check <course>      # validate + a11y (run before export)
+pnpm export <course>     # build a SCORM / cmi5 / web package
+```
+
+Authoring with an AI agent? See [`AGENTS.md`](./AGENTS.md) — it loads the full guide
+and has a **Project notes** section where you add your own context (audience, tone,
+brand).

packages/create-tessera/tests/scaffold.test.ts

@@ -105,6 +105,7 @@ describe('create-tessera workspace scaffold', () => {
     expect(existsSync(resolve(ws, '.gitignore'))).toBe(true);
     expect(existsSync(resolve(ws, 'AGENTS.md'))).toBe(true);
     expect(existsSync(resolve(ws, 'CLAUDE.md'))).toBe(true);
+    expect(existsSync(resolve(ws, 'README.md'))).toBe(true);
     expect(existsSync(resolve(ws, 'shared/Button.svelte'))).toBe(true);
     expect(existsSync(resolve(ws, 'shared/tokens.css'))).toBe(true);
     // No course content at the workspace root — courses live under courses/.
@@ -165,11 +166,25 @@ describe('create-tessera workspace scaffold', () => {
     const claude = readFileSync(resolve(ws, 'CLAUDE.md'), 'utf-8');
     expect(claude).toBe(agents);
     expect(agents).toContain('@./node_modules/tessera-learn/AGENTS.md');
+    expect(agents).toContain('## Project notes');
     expect(agents.length).toBeLessThan(2000);
     // Pointers live only at the root — never stamped per course.
     expect(existsSync(resolve(ws, SEED, 'AGENTS.md'))).toBe(false);
   });
 
+  it('scaffolds a human-facing README headed by the workspace name, not the guide', () => {
+    runCLI('my-courses', testDir);
+    const readme = readFileSync(
+      resolve(testDir, 'my-courses', 'README.md'),
+      'utf-8',
+    );
+    expect(readme).toContain('# my-courses');
+    expect(readme).toContain('pnpm install');
+    expect(readme).toContain('pnpm dev starter-course');
+    expect(readme).toContain('AGENTS.md');
+    expect(readme).not.toContain('@./node_modules/tessera-learn/AGENTS.md');
+  });
+
   it('derives the seed course title from the course name', () => {
     runCLI('my-courses', testDir);
     const config = readFileSync(