diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 000000000..da41730ed
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,25 @@
+# Agent guidelines for newspack-theme
+
+This file covers what is specific to `newspack-theme`. Shared conventions (Docker commands, `n` script, coding standards, git rules, etc.) are in the root `newspack-workspace/AGENTS.md`.
+
+## Overview
+
+`newspack-theme` is a classic WordPress theme (not a block theme) providing the design foundation for Newspack sites. The repository contains the base theme and five child themes that share its codebase:
+
+- `newspack-theme` — Base theme. All child themes extend this.
+- `newspack-joseph`, `newspack-katharine`, `newspack-nelson`, `newspack-sacha`, `newspack-scott` — Child themes. Cosmetic variants only (colors, typography accents). Identical in features.
+
+**Repository layout quirk**: The base theme lives at `newspack-theme/newspack-theme/`, not at the repo root. The repo root holds the shared build tooling (webpack, SCSS compiler, package.json) that compiles assets for all six themes at once.
+
+## Common Gotchas
+
+- **`npm run lint` skips PHP.** Run `npm run lint:php` separately for PHP linting.
+- **No Composer autoloading.** There are only two PHP classes (`Newspack_SVG_Icons`, `Newspack_Walker_Comment`), both manually required in `functions.php`. No namespace is used. Do not introduce PSR-4 autoloading or namespaces.
+- **SCSS compilation uses a custom Node script**, not standard webpack/PostCSS. `scripts/compile-scss.js` handles all themes, RTL generation, and cssnano optimization. Don't try to run it through webpack.
+- **Webpack entry points are auto-discovered.** Any `newspack-theme/js/src/*.js` file or `newspack-theme/js/src/*/index.js` file becomes an entry point automatically. No changes to `webpack.config.js` are needed when adding JS files that follow this convention.
+- **Do not add feature code to child themes.** All feature development belongs in the base `newspack-theme`. Child themes are cosmetic variants only.
+- **This is a classic theme, not a block theme.** It has no `theme.json`. Template changes happen in PHP files, not the Site Editor. Colors, typography, and layout are managed through the Customizer, not `theme.json`.
+- **The theme exposes hooks consumed by Newspack plugins and third-party integrations.** Before removing or renaming any `apply_filters` or `do_action` call, check whether it has external consumers — it may be a breaking change.
+- **AMP code is legacy.** The codebase contains AMP-aware branches throughout (`newspack_is_amp()`, `amp-fallback.js`, etc.). Do not remove this code, but do not add AMP support to new features. New development does not need to consider the AMP path.
+- **Child theme SCSS uses relative `@use` paths back to the base theme** (e.g., `@use "../../newspack-theme/sass/style-base"`). These paths break if directory structure changes.
+- **`single-feature.php` and `single-wide.php` are near-identical templates.** Changes to one almost always need to be applied to the other.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 000000000..43c994c2d
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md
diff --git a/README.md b/README.md
index 94564e67a..cc9a886a1 100644
--- a/README.md
+++ b/README.md
@@ -26,6 +26,67 @@ The Newspack theme repository contains the Newspack parent theme in a subdirecto
 - Run `npm start` to compile the SCSS and JS files, and start file watcher.
 - Run `npm run build` to perform a single compilation run.
 
+### Repository Structure
+
+The repository contains the base theme and five child themes:
+
+- `newspack-theme/` — Base theme. All child themes extend this.
+- `newspack-joseph/`, `newspack-katharine/`, `newspack-nelson/`, `newspack-sacha/`, `newspack-scott/` — Child themes. Cosmetic variants only (colors, typography accents); identical in features.
+
+The build tooling at the repo root compiles assets for all six themes in a single pass. There is no per-theme build command.
+
+### PHP Structure
+
+Key files in `newspack-theme/inc/`:
+
+| File | Purpose |
+|------|---------|
+| `customizer.php` | All Customizer settings: colors, typography, header/footer layout |
+| `template-functions.php` | Template hooks, body class additions, content filters |
+| `template-tags.php` | Template tag functions for post meta, author info, dates, reading time |
+| `color-patterns.php` | Converts Customizer color settings into inline CSS |
+| `typography.php` | Font loading and custom typography CSS generation |
+| `icon-functions.php` | SVG icon helpers |
+
+Plugin integrations (WooCommerce, Jetpack, Yoast, etc.) each have their own file in `inc/` and are only loaded when the relevant plugin is active.
+
+### SCSS Structure
+
+Source SCSS lives in `newspack-theme/sass/` and is compiled by a custom Node script (`scripts/compile-scss.js`) that handles all themes, RTL generation, and minification.
+
+Key subdirectories:
+
+| Directory | Contents |
+|-----------|----------|
+| `blocks/` | Gutenberg block styles |
+| `elements/` | Lists, tables, and basic HTML elements |
+| `layout/` | Grid and layout utilities |
+| `mixins/` | SCSS mixins |
+| `modules/` | Component modules (cards, bylines, etc.) |
+| `navigation/` | Menu and nav styles |
+| `plugins/` | Integration styles (WooCommerce, Newsletters, Sponsors, etc.) |
+| `site/` | Header, footer, sidebar styles |
+
+Child themes have their own `sass/` directories with override files compiled alongside the base theme.
+
+### Child Themes
+
+The child themes share the base theme's features entirely — differences are purely cosmetic. To switch between child themes, use **Appearance > Themes** in wp-admin. Switching via the Customizer does not reliably transfer settings between themes.
+
+Each child theme follows the same structure:
+
+```
+newspack-<name>/
+├── functions.php         # Enqueues child styles, hooks color/typography CSS
+├── style.css             # Theme header + generated CSS
+├── style-editor.css      # Generated editor styles
+├── style-rtl.css         # Generated RTL styles
+├── inc/
+│   ├── child-color-patterns.php  # Child-specific color CSS generation
+│   └── child-typography.php     # Child-specific typography CSS generation
+└── sass/                 # SCSS overrides compiled alongside the base theme
+```
+
 ## Support or Questions
 
 This repository is not suitable for support or general questions about Newspack. Please only use our issue trackers for bug reports and feature requests, following [the contribution guidelines](https://github.com/Automattic/newspack-theme/blob/trunk/.github/CONTRIBUTING.md).