diff --git a/themes/10up-block-theme/README.md b/themes/10up-block-theme/README.md
new file mode 100644
index 00000000..4f76f0d2
--- /dev/null
+++ b/themes/10up-block-theme/README.md
@@ -0,0 +1,289 @@
+# 10up Block Theme
+
+## Overview
+This is a lightweight starter theme for WordPress block themes. It provides the minimal structure to get a modern full-site editing theme up and running, while also being easy to extend.
+
+## Goals
+- Fast setup for new WordPress engineers
+- Clear convention-based project structure
+- Build on WordPress block theme best practices
+- Keep PHP logic minimal and isolated in `src/`
+
+## Project Structure
+- `assets/`: theme asset source files (CSS, JS, fonts, images)
+- `blocks/`: custom blocks
+- `parts/`: reusable theme parts for header, footer, etc.
+- `patterns/`: block pattern PHP registration / markup
+- `src/`: PHP classes for theme setup, block registration, asset loading
+- `templates/`: full-site editing template files
+
+Comprehensive developer guide:
+- Architecture
+- Build tools
+- WordPress connections
+- Blocks
+- Templates
+- Runtime behavior
+
+---
+
+## 1. Theme overview
+
+This is a full-site block theme built using:
+- WordPress block theme system (`theme.json`, template files, template parts)
+- 10up toolkit (`10up-toolkit`) for asset bundling, linting, testing
+- 10up framework (`10up/wp-framework`) for modular PHP class loading
+- Modern CSS and JS modules in `assets/`
+- Custom blocks under `blocks/`
+
+Main root files:
+- `style.css` - WordPress theme header and bare stylesheet.
+- `theme.json` - block theme settings, styles, color/spacing scales, templates.
+- `functions.php` - Bootstrap: constants, composer loading, fast-refresh and theme setup.
+- `composer.json` - PHP dependencies and PSR-4 autoload.
+- `package.json` - JS/asset build and 10up-toolkit configuration.
+
+---
+
+## 2. Requirements
+
+- PHP >= 8.2
+- Node >= 18
+- Composer
+- WordPress 6.8+ (implied by theme.json schema)
+
+---
+
+## 3. First-time setup
+
+1. Clone the repository:
+   ```bash
+   git clone <repo-url> 10up-block-theme
+   cd 10up-block-theme
+   ```
+2. Install dependencies:
+   ```bash
+   composer install
+   npm install
+   ```
+3. Build assets:
+   ```bash
+   npm run build
+   ```
+4. Activate theme in WordPress admin: Appearance → Themes → "10up Block Theme"
+
+---
+
+## 4. Developer workflow
+
+### 4.1 Quick start (repeat for copy/paste)
+
+```bash
+cd /path/to/themes/10up-block-theme
+composer install
+npm install
+npm run build
+```
+
+### 4.2 Local development
+
+- `npm run watch` (or `npm start`) → 10up-toolkit watch with HMR/hot-refresh
+- `composer exec phpcs -- --standard=WordPress` → PHP lint
+- `npm run lint` → JS lint
+- `npm run lint-style` → CSS lint
+- `npm run test` → unit tests
+- `npm run clean-dist` → remove generated assets
+
+### 4.3 Common gotchas
+
+- Always build `dist/` after changing source assets (`assets/`, `blocks/`, `src/`).
+- If using a check-in strategy for `dist/`, ensure CI runs `npm run build` before release.
+- `theme.json` is the source of truth for editor styles, palette, and layout. Adjust there for global styles.
+- Some references may still use legacy naming in older helper docs; prefer 10up-block-theme naming in code changes.
+
+---
+
+## 5. Core bootstrapping path
+
+### 5.1 `functions.php`
+
+- defines constants:
+  - `TENUP_BLOCK_THEME_PATH`, `TENUP_BLOCK_THEME_DIST_PATH`, `TENUP_BLOCK_THEME_INC`, etc.
+- points to composer/autoload (`vendor/autoload.php`)
+- local fast-refresh via `dist/fast-refresh.php` when local environment
+- includes helper files:
+  - `includes/helpers.php`
+  - `template-tags.php`
+- creates and sets up `\TenupBlockTheme\ThemeCore`.
+
+### 5.2 `src/ThemeCore.php`
+
+- hooks:
+  - `init` → `ThemeCore::init()`
+  - `after_setup_theme` → `i18n()` + `theme_setup()`
+  - `wp_head` → `js_detection()` + `scrollbar_detection()`
+- `init()` ensures `TenupFramework\ModuleInitialization` exists, admin notice on failure
+- `ModuleInitialization::instance()->init_classes( TENUP_BLOCK_THEME_INC )` automatically loads modules from `src/`.
+
+---
+
+## 6. Module system (10up framework)
+
+By `ThemeCore::init()`, `\TenupFramework\ModuleInitialization` scans `src/` and initializes modules that implement `ModuleInterface`.
+
+Current modules:
+- `src/Blocks.php` (block registration and enqueueing)
+- `src/Overrides.php` (WP output filters such as post date text for custom post types)
+- `src/TemplateTags.php` (meta tag injection on `wp_head`)
+
+Each module uses `TenupFramework\Module` trait to register hooks easily.
+
+---
+
+## 6. Block registration & runtime
+
+### 6.1 `src/Blocks.php`
+
+- `register_theme_blocks()` scans `dist/blocks/*/block.json` and calls `register_block_type_from_metadata()` for each found block.
+- `allowed_block_types_all` filter extends allowed blocks with theme blocks.
+- `enqueue_theme_block_styles()` scans `dist/blocks/autoenqueue/**/*.css` and registers/enqueues style/script for each block with assets info from `GetAssetInfo`.
+- includes block render filter for TenUp navigation block (removes ARIA roles for fallback markup compatibility).
+
+### 6.2 Blocks directory structure
+
+`blocks/` contains block sources with standard WP block scaffold:
+- `block.json`
+- `edit.tsx`, `index.ts`, `markup.php`
+- `style.css` / `editor.css` (for block styles)
+
+`blocks/*` are transpiled and bundled by 10up-toolkit into `dist/blocks/*` (JS/CSS/asset metadata files).
+
+---
+
+## 7. Asset pipeline (10up-toolkit)
+
+`package.json` includes a `10up-toolkit` config section:
+- `useBlockAssets`: true (auto-handle block assets)
+- `useScriptModules`: true
+- `loadBlockSpecificStyles`: true
+- `entry` maps compiled assets:
+  - `editor-style-overrides`: `assets/css/editor-style-overrides.css`
+  - `frontend`: `assets/js/frontend.ts`
+  - `block-extensions`: `assets/js/block-editor/index.ts`
+- `paths.blocksDir`: `./blocks`
+
+`npm run build` calls `10up-toolkit build` and outputs to `dist/*`.
+
+`npm run watch` does incremental build with file watching.
+
+### 7.1 Dist layout
+
+- `dist/css/` (compiled styles)
+- `dist/js/` (compiled scripts)
+- `dist/blocks/` (compiled block assets per block)
+- `dist/fast-refresh.php` (local live-reload helper)
+
+### 7.2 Theme script inclusion
+
+- `src/ThemeCore::theme_setup()` calls `add_theme_support('editor-styles')` and `add_editor_style('/dist/css/frontend.css')`.
+- Additional frontend script injection is likely handled in block metadata and `10up-toolkit` output, not explicit in theme code.
+
+---
+
+## 8. Styles + theme.json
+
+### `theme.json`
+
+Defines:
+- `templateParts`: `header`, `footer`
+- `customTemplates` for special post types
+- `settings` with custom properties (`--wp--custom--*`, width computations, spacing, color palettes, gradients, transition variables)
+- `layout` with content and wide max widths.
+
+### `assets/css/` structure
+
+- `editor-style-overrides.css` for editor-specific style overrides
+- `frontend.css` for visual styles
+- subdirectories for base/blocks/components/globals/mixins/patterns/templates/utilities
+
+### `parts/` partial PHP templates
+- `parts/header.html`, `parts/footer.html`, etc.
+
+### `patterns/` reusable partial definitions
+- e.g., `base-card.php`, etc.
+
+---
+
+## 9. Template and content hierarchy
+
+`templates/` uses static HTML templates for site result paths:
+- `index.html`, `home.html`, `single.html`, etc.
+
+These are block theme templates in Full Site Editing model.
+
+---
+
+## 10. WordPress hook behavior at runtime
+
+- `wp_head`:
+  - `ThemeCore::js_detection()` toggles `no-js` to `js`
+  - `ThemeCore::scrollbar_detection()` sets `--wp--custom--scrollbar-width`
+  - `TemplateTags::add_viewport_meta_tag()` outputs viewport meta
+
+- `after_setup_theme`: editor styles + disable core block patterns.
+
+- `init`: loads module classes and runs block registration.
+
+---
+
+## 11. Debug and local enhancement
+
+- local environment scenario (`.local`/`.test` or `local`/`development`) loads `dist/fast-refresh.php` and sets dist URL path with `TenUpToolkit\set_dist_url_path()` for hot-reload.
+
+---
+
+## 12. Extending the theme
+
+1. Add block in `blocks/<block-name>/`.
+2. Create `block.json`, `edit.tsx`, `index.ts`, style files as needed.
+3. Run `npm run build`.
+4. Block registers automatically from `dist/blocks/*` in `Blocks::register_theme_blocks()`.
+
+---
+
+## 13. Maintenance tasks
+
+- PHP lint: `composer lint`
+- JS lint: `npm run lint` / `npm run lint-js`
+- Style lint: `npm run lint-style`
+- Format JS: `npm run format-js`
+- Clean dist: `npm run clean-dist`
+
+---
+
+## 14. Key entrypoints quick map
+
+- `functions.php` → `ThemeCore` → class loader
+- `src/Blocks.php` → block metadata and enqueueing
+- `assets/js/frontend.ts` → frontend script implementation
+- `blocks/*` + `10up-toolkit` → `dist/blocks/*`
+- `theme.json` → WordPress UI/Editor settings
+
+---
+
+## 15. Helpful commands summary
+
+- `composer install`
+- `npm install`
+- `npm run watch`
+- `npm run build`
+- `composer exec phpcs -- --standard=WordPress`
+- `npm test`
+- `npm run lint`
+
+---
+
+## 16. Further notes
+
+- This theme is designed around a 10up block theme pattern (colors, spacing, utilities, templates).
+- The 10up Toolkit plus the WP framework yields a highly modular, maintainable code path and is production-ready.
diff --git a/themes/10up-block-theme/assets/README.md b/themes/10up-block-theme/assets/README.md
new file mode 100644
index 00000000..b0977a20
--- /dev/null
+++ b/themes/10up-block-theme/assets/README.md
@@ -0,0 +1,19 @@
+# assets/
+
+Contains static theme assets. Use this folder to keep the theme's source CSS, JavaScript, fonts, and images.
+
+## Subfolders
+- `css/`: core styles and split source files (`base`, `blocks`, `components`, `globals`, `mixins`, `templates`, `utilities`)
+- `fonts/`: font files used by theme
+- `images/`: image assets used in templates/patterns
+- `js/`: JavaScript entrypoints and block feature extensions
+- `svg/`: inline svg icons or assets
+
+## How to use
+- Keep editable CSS here.
+- `js/frontend.js`: theme front-end behavior
+- `js/block-*`: block variations, filters, styles, and extensions
+
+## Notes
+- Changes in this folder typically require a page refresh and sometimes rebuild. 
+- When adding CSS for blocks, prefer adding to `assets/css/blocks/core/` to avoid global overrides.
diff --git a/themes/10up-block-theme/assets/js/block-extensions.js b/themes/10up-block-theme/assets/js/block-extensions.ts
similarity index 100%
rename from themes/10up-block-theme/assets/js/block-extensions.js
rename to themes/10up-block-theme/assets/js/block-extensions.ts
diff --git a/themes/10up-block-theme/assets/js/block-filters/index.js b/themes/10up-block-theme/assets/js/block-filters/index.ts
similarity index 100%
rename from themes/10up-block-theme/assets/js/block-filters/index.js
rename to themes/10up-block-theme/assets/js/block-filters/index.ts
diff --git a/themes/10up-block-theme/assets/js/block-styles/index.js b/themes/10up-block-theme/assets/js/block-styles/index.ts
similarity index 100%
rename from themes/10up-block-theme/assets/js/block-styles/index.js
rename to themes/10up-block-theme/assets/js/block-styles/index.ts
diff --git a/themes/10up-block-theme/assets/js/block-variations/index.js b/themes/10up-block-theme/assets/js/block-variations/index.ts
similarity index 100%
rename from themes/10up-block-theme/assets/js/block-variations/index.js
rename to themes/10up-block-theme/assets/js/block-variations/index.ts
diff --git a/themes/10up-block-theme/assets/js/block-variations/unregister-variations.js b/themes/10up-block-theme/assets/js/block-variations/unregister-variations.ts
similarity index 100%
rename from themes/10up-block-theme/assets/js/block-variations/unregister-variations.js
rename to themes/10up-block-theme/assets/js/block-variations/unregister-variations.ts
diff --git a/themes/10up-block-theme/assets/js/frontend.js b/themes/10up-block-theme/assets/js/frontend.ts
similarity index 100%
rename from themes/10up-block-theme/assets/js/frontend.js
rename to themes/10up-block-theme/assets/js/frontend.ts
diff --git a/themes/10up-block-theme/blocks/README.md b/themes/10up-block-theme/blocks/README.md
new file mode 100644
index 00000000..6b03a8b6
--- /dev/null
+++ b/themes/10up-block-theme/blocks/README.md
@@ -0,0 +1,16 @@
+# blocks/
+
+Library of custom blocks for a theme
+
+## Purpose
+- Create custom blocks for a theme
+
+## Example block: `example-block` (hello world)
+1. Create `blocks/example-block/block.json` with metadata
+2. Add `blocks/example-block/edit.tsx` and `blocks/example-block/index.ts`:
+   - `BlockEdit` renders editor UI
+   - `registerBlockType(metadata, { edit: BlockEdit, save: () => null })`
+3. Add `blocks/example-block/markup.php` to output frontend markup:
+   - Simple output: `<div class="wp-block-tenup-block-theme-example-block">Hello world</div>`
+4. Add `blocks/example-block/style.css` for block style
+5. Build the block bundle with `npm run build`
\ No newline at end of file
diff --git a/themes/10up-block-theme/blocks/example-block/block.json b/themes/10up-block-theme/blocks/example-block/block.json
new file mode 100644
index 00000000..f8a84b21
--- /dev/null
+++ b/themes/10up-block-theme/blocks/example-block/block.json
@@ -0,0 +1,17 @@
+{
+	"$schema": "https://schemas.wp.org/trunk/block.json",
+	"apiVersion": 3,
+	"name": "tenup-block-theme/example-block",
+	"title": "Example Block",
+	"category": "theme",
+	"icon": "smiley",
+	"description": "A minimal example block for new block authors that renders Hello World.",
+    "attributes": {},
+	"supports": {
+		"html": false
+	},
+	"textdomain": "tenup",
+	"editorScript": "file:./index.ts",
+	"style": "file:./style.css",
+	"render": "file:./markup.php"
+}
diff --git a/themes/10up-block-theme/blocks/example-block/edit.tsx b/themes/10up-block-theme/blocks/example-block/edit.tsx
new file mode 100644
index 00000000..6fc4890c
--- /dev/null
+++ b/themes/10up-block-theme/blocks/example-block/edit.tsx
@@ -0,0 +1,11 @@
+import { useBlockProps } from '@wordpress/block-editor';
+
+export const BlockEdit = () => {
+	const blockProps = useBlockProps();
+
+	return (
+		<div {...blockProps}>
+			<strong>Example Block:</strong> Hello world
+		</div>
+	);
+};
diff --git a/themes/10up-block-theme/blocks/example-block/index.ts b/themes/10up-block-theme/blocks/example-block/index.ts
new file mode 100644
index 00000000..b7a7f8fc
--- /dev/null
+++ b/themes/10up-block-theme/blocks/example-block/index.ts
@@ -0,0 +1,11 @@
+import { registerBlockType, type BlockConfiguration } from '@wordpress/blocks';
+import metadata from './block.json';
+import { BlockEdit } from './edit';
+
+const blockMeta = metadata as unknown as BlockConfiguration<Record<string, unknown>>;
+const blockName = blockMeta.name as string;
+
+registerBlockType(blockMeta, {
+	edit: BlockEdit,
+	save: () => null,
+});
diff --git a/themes/10up-block-theme/blocks/example-block/markup.php b/themes/10up-block-theme/blocks/example-block/markup.php
new file mode 100644
index 00000000..52e15ba9
--- /dev/null
+++ b/themes/10up-block-theme/blocks/example-block/markup.php
@@ -0,0 +1,16 @@
+<?php
+/**
+ * Example block markup
+ *
+ * @package 10up-block-theme
+ *
+ * @var array    $attributes         Block attributes.
+ * @var string   $content            Block content.
+ * @var WP_Block $block              Block instance.
+ * @var array    $context            Block context.
+ */
+
+?>
+<div <?php echo get_block_wrapper_attributes(); // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped ?>>
+	<strong>Example Block:</strong> Hello world
+</div>
\ No newline at end of file
diff --git a/themes/10up-block-theme/blocks/example-block/style.css b/themes/10up-block-theme/blocks/example-block/style.css
new file mode 100644
index 00000000..bc27317b
--- /dev/null
+++ b/themes/10up-block-theme/blocks/example-block/style.css
@@ -0,0 +1,6 @@
+.wp-block-tenup-block-theme-example-block {
+	background: #f5f5f5;
+	border: 1px dashed #0073aa;
+	font-weight: 600;
+	padding: 1rem;
+}
diff --git a/themes/10up-block-theme/composer.json b/themes/10up-block-theme/composer.json
index bdc93d3f..ed7ed5fe 100644
--- a/themes/10up-block-theme/composer.json
+++ b/themes/10up-block-theme/composer.json
@@ -1,5 +1,5 @@
 {
-  "name": "10up/tenup-theme",
+  "name": "10up/tenup-block-theme",
   "type": "wordpress-theme",
   "authors": [
     {
diff --git a/themes/10up-block-theme/package.json b/themes/10up-block-theme/package.json
index 170d70ec..3a9ee38c 100644
--- a/themes/10up-block-theme/package.json
+++ b/themes/10up-block-theme/package.json
@@ -13,11 +13,6 @@
 		"clean-dist": "rm -rf ./dist",
 		"scaffold:block": "cd blocks/ && wp-create-block --no-plugin --template ../../../../bin/create-block-template"
 	},
-	"dependencies": {
-		"@10up/block-components": "^1.19.4",
-		"10up-toolkit": "^6.5.1",
-		"clsx": "^2.1.1"
-	},
 	"10up-toolkit": {
 		"useBlockAssets": true,
 		"useScriptModules": true,
@@ -31,5 +26,29 @@
 		"paths": {
 			"blocksDir": "./blocks"
 		}
+	},
+	"optionalDependencies": {
+		"@wordpress/api-fetch": "^7.41.0",
+		"@wordpress/block-editor": "^15.14.0",
+		"@wordpress/blocks": "^15.14.0",
+		"@wordpress/components": "^32.3.0",
+		"@wordpress/compose": "^7.41.0",
+		"@wordpress/core-data": "^7.41.0",
+		"@wordpress/data": "^10.41.0",
+		"@wordpress/dom-ready": "^4.41.0",
+		"@wordpress/editor": "^14.41.0",
+		"@wordpress/hooks": "^4.41.0",
+		"@wordpress/i18n": "^6.14.0",
+		"@wordpress/interactivity": "^6.41.0",
+		"@wordpress/plugins": "^7.41.0",
+		"@wordpress/server-side-render": "^6.17.0"
+	},
+	"dependencies": {
+		"@10up/block-components": "^1.22.1",
+		"10up-toolkit": "^6.5.1"
+	},
+	"devDependencies": {
+		"@types/wordpress__block-editor": "^15.0.5",
+		"@types/wordpress__blocks": "^15.10.2"
 	}
 }
diff --git a/themes/10up-block-theme/parts/README.md b/themes/10up-block-theme/parts/README.md
new file mode 100644
index 00000000..840f82fb
--- /dev/null
+++ b/themes/10up-block-theme/parts/README.md
@@ -0,0 +1,15 @@
+# parts/
+
+Reusable theme parts used in block templates and patterns.
+
+## Contents
+- `header.html`, `footer.html`, and area-specific part files like `site-header-navigation-area.html` and `site-footer-legal-navigation-area.html`.
+
+## Usage
+- Use these as `template-part` blocks from the Site Editor (Appearance -> Editor).
+- Keep markup minimal: structure and block placeholders, avoid heavy styling directly in these files.
+- Update in the Site Editor to automatically persist changes if desired, or use these files as source-of-truth for versioned code.
+
+## Example
+Create `parts/site-header-navigation-area.html` with a `navigation` block and save. In `templates/index.html`, include it as `<!-- wp:template-part {"slug":"site-header-navigation-area"} /-->`.
+
diff --git a/themes/10up-block-theme/patterns/README.md b/themes/10up-block-theme/patterns/README.md
new file mode 100644
index 00000000..6f170b57
--- /dev/null
+++ b/themes/10up-block-theme/patterns/README.md
@@ -0,0 +1,10 @@
+# patterns/
+
+Block patterns and registration helper files in PHP.
+
+## Purpose
+- Provide reusable block pattern snippets for site editor insertion.
+- Register patterns with WordPress. Example: `patterns/card.php`.
+
+## How to add
+- Create a new pattern PHP file with the WordPress HTML markup for the pattern.
\ No newline at end of file
diff --git a/themes/10up-block-theme/patterns/card.php b/themes/10up-block-theme/patterns/base-card.php
similarity index 98%
rename from themes/10up-block-theme/patterns/card.php
rename to themes/10up-block-theme/patterns/base-card.php
index 155c72b2..d8d96289 100644
--- a/themes/10up-block-theme/patterns/card.php
+++ b/themes/10up-block-theme/patterns/base-card.php
@@ -1,7 +1,7 @@
 <?php
 /**
  * Title: Base Card
- * Slug: tenup-theme/base-card
+ * Slug: tenup-block-theme/base-card
  * Description: A card pattern with a featured image, title, date, and category.
  * Inserter: false
  *
diff --git a/themes/10up-block-theme/src/Assets.php b/themes/10up-block-theme/src/Assets.php
index d2bc60e7..302ff20d 100644
--- a/themes/10up-block-theme/src/Assets.php
+++ b/themes/10up-block-theme/src/Assets.php
@@ -53,14 +53,14 @@ public function register() {
 	 */
 	public function enqueue_frontend_assets() {
 		wp_enqueue_style(
-			'tenup-theme-styles',
+			'tenup-block-theme-styles',
 			TENUP_BLOCK_THEME_TEMPLATE_URL . '/dist/css/frontend.css',
 			[],
 			$this->get_asset_info( 'frontend', 'version' )
 		);
 
 		wp_enqueue_script(
-			'tenup-theme-frontend',
+			'tenup-block-theme-frontend',
 			TENUP_BLOCK_THEME_TEMPLATE_URL . '/dist/js/frontend.js',
 			$this->get_asset_info( 'frontend', 'dependencies' ),
 			$this->get_asset_info( 'frontend', 'version' ),
@@ -79,14 +79,14 @@ public function enqueue_frontend_assets() {
 	 */
 	public function enqueue_block_editor_assets() {
 		wp_enqueue_style(
-			'tenup-theme-editor-frame-style-overrides',
+			'tenup-block-theme-editor-frame-style-overrides',
 			TENUP_BLOCK_THEME_TEMPLATE_URL . '/dist/css/editor-frame-style-overrides.css',
 			[],
 			TENUP_BLOCK_THEME_VERSION
 		);
 
 		wp_enqueue_script(
-			'tenup-theme-block-extensions',
+			'tenup-block-theme-block-extensions',
 			TENUP_BLOCK_THEME_TEMPLATE_URL . '/dist/js/block-extensions.js',
 			$this->get_asset_info( 'block-extensions', 'dependencies' ),
 			$this->get_asset_info( 'block-extensions', 'version' ),
@@ -108,7 +108,7 @@ public function enqueue_block_editor_iframe_assets() {
 		}
 
 		wp_enqueue_style(
-			'tenup-theme-editor-canvas-style-overrides',
+			'tenup-block-theme-editor-canvas-style-overrides',
 			TENUP_BLOCK_THEME_TEMPLATE_URL . '/dist/css/editor-canvas-style-overrides.css',
 			[],
 			TENUP_BLOCK_THEME_VERSION
diff --git a/themes/10up-block-theme/src/Blocks.php b/themes/10up-block-theme/src/Blocks.php
index f689eec3..f22007a1 100644
--- a/themes/10up-block-theme/src/Blocks.php
+++ b/themes/10up-block-theme/src/Blocks.php
@@ -103,7 +103,7 @@ public function enqueue_theme_block_styles() {
 			$block_type = str_replace( '.css', '', $block_type );
 
 			wp_register_style(
-				"tenup-theme-{$block_type}",
+				"tenup-block-theme-{$block_type}",
 				TENUP_BLOCK_THEME_DIST_URL . 'blocks/autoenqueue/' . $block_type . '.css',
 				$this->get_asset_info( 'blocks/autoenqueue/' . $block_type, 'dependencies' ),
 				$this->get_asset_info( 'blocks/autoenqueue/' . $block_type, 'version' ),
@@ -112,7 +112,7 @@ public function enqueue_theme_block_styles() {
 			wp_enqueue_block_style(
 				$block_type,
 				[
-					'handle' => "tenup-theme-{$block_type}",
+					'handle' => "tenup-block-theme-{$block_type}",
 					'path'   => $stylesheet_path,
 				]
 			);
diff --git a/themes/10up-block-theme/src/README.md b/themes/10up-block-theme/src/README.md
new file mode 100644
index 00000000..8091ca26
--- /dev/null
+++ b/themes/10up-block-theme/src/README.md
@@ -0,0 +1,21 @@
+# src/
+
+PHP core theme classes and wrapper logic.
+
+## Purpose
+- Keep PHP functions and setup logic organized in class-based files.
+- Avoid scattering code inside `functions.php`.
+
+## Files
+- `Assets.php`: enqueue styles/scripts and add theme support options.
+- `Blocks.php`: block style/variation registration (feature flags, etc.).
+- `TemplateTags.php`: helper functions for templates.
+- `ThemeCore.php`: bootstraps theme features and ties registration callbacks together.
+
+## Best practice
+- Add new features as single-responsibility classes or methods.
+- Keep public API in ThemeCore and specific feature classes.
+
+## Loading
+- `functions.php` should instantiate `ThemeCore` (or similar) and call init actions.
+- Keep `functions.php` as container only, with as little direct logic as possible.
diff --git a/themes/10up-block-theme/src/ThemeCore.php b/themes/10up-block-theme/src/ThemeCore.php
index 20deae07..111e7f69 100644
--- a/themes/10up-block-theme/src/ThemeCore.php
+++ b/themes/10up-block-theme/src/ThemeCore.php
@@ -38,7 +38,7 @@ public function setup() {
 	 * @return void
 	 */
 	public function i18n() {
-		load_theme_textdomain( 'tenup-theme', TENUP_BLOCK_THEME_PATH . '/languages' );
+		load_theme_textdomain( 'tenup-block-theme', TENUP_BLOCK_THEME_PATH . '/languages' );
 	}
 
 	/**
diff --git a/themes/10up-block-theme/styles/surface-primary.json b/themes/10up-block-theme/styles/surface-primary.json
deleted file mode 100644
index e706b638..00000000
--- a/themes/10up-block-theme/styles/surface-primary.json
+++ /dev/null
@@ -1,12 +0,0 @@
-{
-	"$schema": "https://schemas.wp.org/wp/6.7/theme.json",
-	"version": 3,
-	"title": "Primary",
-	"slug": "primary",
-	"blockTypes": [
-		"core/group"
-	],
-	"styles": {
-		"color": {}
-	}
-}
diff --git a/themes/10up-block-theme/styles/surface-secondary.json b/themes/10up-block-theme/styles/surface-secondary.json
deleted file mode 100644
index 939837fe..00000000
--- a/themes/10up-block-theme/styles/surface-secondary.json
+++ /dev/null
@@ -1,12 +0,0 @@
-{
-	"$schema": "https://schemas.wp.org/wp/6.7/theme.json",
-	"version": 3,
-	"title": "Secondary",
-	"slug": "secondary",
-	"blockTypes": [
-		"core/group"
-	],
-	"styles": {
-		"color": {}
-	}
-}
diff --git a/themes/10up-block-theme/styles/surface-tertiary.json b/themes/10up-block-theme/styles/surface-tertiary.json
deleted file mode 100644
index d737e1c6..00000000
--- a/themes/10up-block-theme/styles/surface-tertiary.json
+++ /dev/null
@@ -1,12 +0,0 @@
-{
-	"$schema": "https://schemas.wp.org/wp/6.7/theme.json",
-	"version": 3,
-	"title": "Tertiary",
-	"slug": "tertiary",
-	"blockTypes": [
-		"core/group"
-	],
-	"styles": {
-		"color": {}
-	}
-}
diff --git a/themes/10up-block-theme/templates/README.md b/themes/10up-block-theme/templates/README.md
new file mode 100644
index 00000000..ac109cd6
--- /dev/null
+++ b/themes/10up-block-theme/templates/README.md
@@ -0,0 +1,18 @@
+# templates/
+
+Block Based templates for the theme.
+
+## Files
+- `404.html`
+- `index.html`
+- `single.html`
+- `singular.html`
+
+## How it works
+- These templates are used by WordPress Block Themes to render core view routes.
+- Use block markup in these files and include `template-part` blocks for reusable sections.
+
+## Customization
+- Add new templates (`archive.html`, `page.html`, etc.) as needed.
+- Use the site editor to override templates in the official user interface.
+- Keep templates clean by delegating repeating content to `parts/` template parts.
diff --git a/themes/10up-block-theme/templates/index.html b/themes/10up-block-theme/templates/index.html
index 5a928531..61f1a76b 100644
--- a/themes/10up-block-theme/templates/index.html
+++ b/themes/10up-block-theme/templates/index.html
@@ -8,7 +8,7 @@
 
 		<!-- wp:post-template {"layout":{"type":"grid","columnCount":null,"minimumColumnWidth":"21rem"},"isEntireCardClickable":true} -->
 
-			<!-- wp:pattern {"slug":"tenup-theme/base-card"} /-->
+		<!-- wp:pattern {"slug":"tenup-block-theme/base-card"} /-->
 
 		<!-- /wp:post-template -->
 
diff --git a/themes/10up-block-theme/tsconfig.json b/themes/10up-block-theme/tsconfig.json
new file mode 100644
index 00000000..2495069b
--- /dev/null
+++ b/themes/10up-block-theme/tsconfig.json
@@ -0,0 +1,15 @@
+{
+	"compilerOptions": {
+		"target": "ESNext",
+		"module": "ESNext",
+		"moduleResolution": "Node",
+		"strict": true,
+		"esModuleInterop": true,
+		"resolveJsonModule": true,
+		"jsx": "react-jsx",
+		"isolatedModules": true,
+		"skipLibCheck": true,
+		"typeRoots": ["./types", "./node_modules/@types"]
+	},
+	"include": ["blocks/**/*.ts", "blocks/**/*.tsx", "src/**/*.ts", "src/**/*.tsx", "types/**/*.d.ts"]
+}
diff --git a/themes/10up-block-theme/types/block-json.d.ts b/themes/10up-block-theme/types/block-json.d.ts
new file mode 100644
index 00000000..c2cd21e5
--- /dev/null
+++ b/themes/10up-block-theme/types/block-json.d.ts
@@ -0,0 +1,6 @@
+import type { BlockConfiguration } from '@wordpress/blocks';
+
+declare module '*.json' {
+	const value: BlockConfiguration<Record<string, unknown>>;
+	export default value;
+}