From f96d52a3f9485ad3d860a93903212b1d5e2417c5 Mon Sep 17 00:00:00 2001 From: Derek Redmond Date: Wed, 3 Jun 2026 21:13:29 -0400 Subject: [PATCH 1/7] feat: scaffold a workspace README for the repo front page Co-Authored-By: Claude Opus 4.8 --- .changeset/scaffold-workspace-readme.md | 5 +++++ .../templates/workspace/README.md | 18 ++++++++++++++++++ packages/create-tessera/tests/scaffold.test.ts | 15 +++++++++++++++ 3 files changed, 38 insertions(+) create mode 100644 .changeset/scaffold-workspace-readme.md create mode 100644 packages/create-tessera/templates/workspace/README.md diff --git a/.changeset/scaffold-workspace-readme.md b/.changeset/scaffold-workspace-readme.md new file mode 100644 index 0000000..12f611a --- /dev/null +++ b/.changeset/scaffold-workspace-readme.md @@ -0,0 +1,5 @@ +--- +'create-tessera': patch +--- + +Scaffolded workspaces now include a human-facing `README.md` for the repo's front page, separate from the agent-facing `AGENTS.md`. diff --git a/packages/create-tessera/templates/workspace/README.md b/packages/create-tessera/templates/workspace/README.md new file mode 100644 index 0000000..a0554a2 --- /dev/null +++ b/packages/create-tessera/templates/workspace/README.md @@ -0,0 +1,18 @@ +# __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 # add a course +pnpm export # build a SCORM / cmi5 / web package +``` + +Authoring with an AI agent? See [`AGENTS.md`](./AGENTS.md), which points to the full +guide at `node_modules/tessera-learn/AGENTS.md`. diff --git a/packages/create-tessera/tests/scaffold.test.ts b/packages/create-tessera/tests/scaffold.test.ts index 1bf177c..b80331d 100644 --- a/packages/create-tessera/tests/scaffold.test.ts +++ b/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/. @@ -170,6 +171,20 @@ describe('create-tessera workspace scaffold', () => { 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'); + // Points at the guide rather than duplicating it. + 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( From 43a3bad3075251bc19fcd895ec7bf074f4a38d4d Mon Sep 17 00:00:00 2001 From: Derek Redmond Date: Wed, 3 Jun 2026 21:17:54 -0400 Subject: [PATCH 2/7] feat: add a Project notes section to the scaffolded AGENTS.md Co-Authored-By: Claude Opus 4.8 --- .changeset/scaffold-workspace-readme.md | 2 +- .../templates/workspace/AGENTS.md | 19 +++++++++++++++++-- .../create-tessera/tests/scaffold.test.ts | 2 +- 3 files changed, 19 insertions(+), 4 deletions(-) diff --git a/.changeset/scaffold-workspace-readme.md b/.changeset/scaffold-workspace-readme.md index 12f611a..8d0d041 100644 --- a/.changeset/scaffold-workspace-readme.md +++ b/.changeset/scaffold-workspace-readme.md @@ -2,4 +2,4 @@ 'create-tessera': patch --- -Scaffolded workspaces now include a human-facing `README.md` for the repo's front page, separate from the agent-facing `AGENTS.md`. +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. diff --git a/packages/create-tessera/templates/workspace/AGENTS.md b/packages/create-tessera/templates/workspace/AGENTS.md index d7b46b3..6bd2f8a 100644 --- a/packages/create-tessera/templates/workspace/AGENTS.md +++ b/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 `; run a command against one with -`pnpm tessera dev ` (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 ` (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.)_ diff --git a/packages/create-tessera/tests/scaffold.test.ts b/packages/create-tessera/tests/scaffold.test.ts index b80331d..0d0556b 100644 --- a/packages/create-tessera/tests/scaffold.test.ts +++ b/packages/create-tessera/tests/scaffold.test.ts @@ -166,6 +166,7 @@ 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); @@ -180,7 +181,6 @@ describe('create-tessera workspace scaffold', () => { expect(readme).toContain('# my-courses'); expect(readme).toContain('pnpm install'); expect(readme).toContain('pnpm dev starter-course'); - // Points at the guide rather than duplicating it. expect(readme).toContain('AGENTS.md'); expect(readme).not.toContain('@./node_modules/tessera-learn/AGENTS.md'); }); From 8d095d1dcc0a9152834fcf11d8c7e03f5afbeba8 Mon Sep 17 00:00:00 2001 From: Derek Redmond Date: Wed, 3 Jun 2026 21:18:53 -0400 Subject: [PATCH 3/7] docs: point the README at the AGENTS.md Project notes section Co-Authored-By: Claude Opus 4.8 --- packages/create-tessera/templates/workspace/README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/packages/create-tessera/templates/workspace/README.md b/packages/create-tessera/templates/workspace/README.md index a0554a2..1a9353c 100644 --- a/packages/create-tessera/templates/workspace/README.md +++ b/packages/create-tessera/templates/workspace/README.md @@ -14,5 +14,6 @@ pnpm tessera new # add a course pnpm export # build a SCORM / cmi5 / web package ``` -Authoring with an AI agent? See [`AGENTS.md`](./AGENTS.md), which points to the full -guide at `node_modules/tessera-learn/AGENTS.md`. +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). From 743bbdb34fea2b4bf38ab132a0e0ba1ef60318f4 Mon Sep 17 00:00:00 2001 From: Derek Redmond Date: Wed, 3 Jun 2026 21:22:14 -0400 Subject: [PATCH 4/7] docs: add a Commands reference to the scaffolded README Co-Authored-By: Claude Opus 4.8 --- .../templates/workspace/README.md | 20 ++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/packages/create-tessera/templates/workspace/README.md b/packages/create-tessera/templates/workspace/README.md index 1a9353c..3638f3b 100644 --- a/packages/create-tessera/templates/workspace/README.md +++ b/packages/create-tessera/templates/workspace/README.md @@ -11,7 +11,25 @@ under `courses/`, with a shared design system in `shared/` (imported as `$shared pnpm install pnpm dev starter-course # preview a course in the browser pnpm tessera new # add a course -pnpm export # build a SCORM / cmi5 / web package +``` + +## Commands + +Author: + +```bash +pnpm tessera new # scaffold a new course +pnpm tessera duplicate # copy an existing course +pnpm dev # live preview +``` + +Ship: + +```bash +pnpm validate # check structure & LMS rules +pnpm a11y # accessibility audit +pnpm check # validate + a11y (run before export) +pnpm export # build a SCORM / cmi5 / web package ``` Authoring with an AI agent? See [`AGENTS.md`](./AGENTS.md) — it loads the full guide From f6d0b1c178b88ea3fa036e55a8aa699ccc1a4b8f Mon Sep 17 00:00:00 2001 From: Derek Redmond Date: Wed, 3 Jun 2026 21:23:20 -0400 Subject: [PATCH 5/7] lint --- packages/create-tessera/templates/workspace/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/create-tessera/templates/workspace/README.md b/packages/create-tessera/templates/workspace/README.md index 3638f3b..f19bb96 100644 --- a/packages/create-tessera/templates/workspace/README.md +++ b/packages/create-tessera/templates/workspace/README.md @@ -1,4 +1,4 @@ -# __PROJECT_NAME__ +# **PROJECT_NAME** > Edit this README to describe your course library. From 63d2a2cd90eb5b3c635e08ade812d031c149ea0c Mon Sep 17 00:00:00 2001 From: Derek Redmond Date: Wed, 3 Jun 2026 21:28:51 -0400 Subject: [PATCH 6/7] fix: keep prettier from mangling the README scaffold token prettier reads __PROJECT_NAME__ as markdown bold and had rewritten it to **PROJECT_NAME**, so copyTemplate never substituted the workspace name. Restore the token and add the template README to .prettierignore. Co-Authored-By: Claude Opus 4.8 --- .prettierignore | 3 +++ packages/create-tessera/templates/workspace/README.md | 2 +- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/.prettierignore b/.prettierignore index afe21af..b0d0000 100644 --- a/.prettierignore +++ b/.prettierignore @@ -7,3 +7,6 @@ tests/.e2e-variants/** pnpm-lock.yaml CHANGELOG.md *.tsbuildinfo + +# prettier reads __PROJECT_NAME__ as markdown bold and rewrites the scaffold token +packages/create-tessera/templates/workspace/README.md diff --git a/packages/create-tessera/templates/workspace/README.md b/packages/create-tessera/templates/workspace/README.md index f19bb96..3638f3b 100644 --- a/packages/create-tessera/templates/workspace/README.md +++ b/packages/create-tessera/templates/workspace/README.md @@ -1,4 +1,4 @@ -# **PROJECT_NAME** +# __PROJECT_NAME__ > Edit this README to describe your course library. From 7d0a7dd6548b889626286a44edf83bf258df203b Mon Sep 17 00:00:00 2001 From: Derek Redmond Date: Wed, 3 Jun 2026 21:29:19 -0400 Subject: [PATCH 7/7] chore: drop the .prettierignore comment Co-Authored-By: Claude Opus 4.8 --- .prettierignore | 2 -- 1 file changed, 2 deletions(-) diff --git a/.prettierignore b/.prettierignore index b0d0000..9c0aaa1 100644 --- a/.prettierignore +++ b/.prettierignore @@ -7,6 +7,4 @@ tests/.e2e-variants/** pnpm-lock.yaml CHANGELOG.md *.tsbuildinfo - -# prettier reads __PROJECT_NAME__ as markdown bold and rewrites the scaffold token packages/create-tessera/templates/workspace/README.md