Core docs upgrades

.gitignore

@@ -19,3 +19,28 @@ npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
 .yarn/install-state.gz
+/core
+.cursor/plans
+refs
+.gitignore
+hooks
+HEAD
+.gitignore
+objects
+config
+.zshrc
+.zprofile
+.ripgreprc
+.profile
+.mcp.json
+.gitignore
+.idea
+.gitmodules
+.gitconfig
+.bashrc
+.bash_profile
+.claude/agents
+.claude/commands
+.claude/settings.json
+.claude/skills
+tmp/

CLAUDE.md

@@ -0,0 +1,69 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this repo is
+
+Docusaurus v3 documentation site for the [Digital Alchemy](https://docs.digital-alchemy.app) TypeScript framework — a batteries-included, low-dependency Node.js framework for type-safe Home Assistant automation and general-purpose apps. The docs cover three main areas: **Core** (framework internals), **Home Automation** (hass + synapse integrations), and **Support Libraries** (mqtt, etc.).
+
+## Commands
+
+```bash
+yarn start          # local dev server with hot reload
+yarn build          # production build to build/
+yarn typecheck      # tsc type-check (tsconfig.json)
+yarn clear          # clear Docusaurus cache
+yarn serve          # serve the built site locally
+```
+
+No test suite — `yarn typecheck` is the main code quality check.
+
+**Important:** `onBrokenLinks: "throw"` in `docusaurus.config.ts` means broken internal links will fail the build. Verify all cross-doc links when moving or renaming files.
+
+## Docs structure
+
+```
+docs/
+  core/             # @digital-alchemy/core framework
+  home-automation/  # hass/, synapse/, testing/
+  support/          # mqtt/, etc.
+  testing/          # general testing docs
+```
+
+Sidebars are **fully auto-generated** from the filesystem (`autogenerated: true` in `sidebars.ts`). Page order and nesting come from directory structure and frontmatter `sidebar_position`.
+
+## MDX and components
+
+Docs are `.md` or `.mdx`. Use `.mdx` when a page needs React components (e.g. `EmbeddedEditor`).
+
+### EmbeddedEditor
+
+An interactive Monaco editor with TypeScript IntelliSense embedded in docs. It uses `@typescript/ata` to auto-acquire type definitions for `@digital-alchemy/core` from npm on first load.
+
+Currently the component has hardcoded example files in `src/components/EmbeddedEditor/init.ts`. The planned refactor (tracked in `.cursor/plans/core-docs-structure.plan.md`) changes the API to accept `files: Record<string, string>` and `defaultFile?: string` as props, with examples moved to `src/examples/core/`.
+
+Usage in MDX:
+```mdx
+import EmbeddedEditor from '@site/src/components/EmbeddedEditor/index';
+
+<EmbeddedEditor />
+```
+
+### Mermaid diagrams
+
+Enabled via `@docusaurus/theme-mermaid`. Use fenced code blocks with ` ```mermaid `.
+
+## Custom plugin
+
+`plugins/webpack-fallback.ts` — resolves Node.js built-in `module` to `false` in the browser bundle, required for `@typescript/ata` to work in the browser.
+
+## Active architectural plan
+
+`.cursor/plans/core-docs-structure.plan.md` describes a major restructuring of `docs/core/` from feature-area folders (`configuration/`, `applications/`, `services/`, etc.) into an intent-based hierarchy: `get-started/` → `tutorials/` → `reference/` → `guides/` → `advanced/`. ~26 current pages expand to ~60. The plan also specifies an `EmbeddedEditor` refactor and a new `src/examples/core/` directory. Check this plan before making changes to `docs/core/` structure.
+
+## Docusaurus-specific conventions
+
+- Frontmatter fields in use: `title`, `id`, `sidebar_position`, `description`
+- `sidebar_label` can override the display name in the sidebar independently of `title`
+- The `id` field in frontmatter determines the slug used in cross-doc links (e.g. `[link](./some-doc)` resolves by `id` or filename)
+- Blog lives in `blog/` and is separate from versioned docs