chore(release): merge v0.0.2 to main

This release includes monorepo architecture, comprehensive documentation
infrastructure, CI automation, and pre-release governance tooling.

See RELEASE-v0.0.2.md for detailed changelog.

Author: watthem

.agents/AGENTS.md

@@ -0,0 +1,38 @@
+# Repository Guidelines
+
+This repository is a JavaScript/TypeScript monorepo for front.js. Keep changes small, security-minded, and aligned with the size budget of the core runtime.
+
+## Project Structure & Module Organization
+- `packages/core/src/` — core runtime; public API re-exported via `packages/core/src/index.js`.
+- `packages/actions/src/` — RPC/actions layer (`client.js`, `server.js`).
+- `src/` — legacy/root entry points used by the website/KB builds.
+- `tests/` and `packages/core/tests/` — Vitest suites; mirror core behavior and security checks.
+- `website/` and `docs/` — marketing site, KB, and generated API docs; `website/examples/` for manual verification.
+- `scripts/` — utility tasks (filename validation, API docs generation).
+
+## Build, Test, and Development Commands
+- `npm install` (Node >= 18) — install workspace deps.
+- `npm run build` — build all workspaces; `npm run build -w @frontjs/core` for the core only.
+- `npm test` — run Vitest suites across workspaces; `npm run test:watch -w @frontjs/core` for watch mode.
+- `npm run lint` / `npm run format` — enforce ESLint and Prettier on JS and Markdown.
+- `npm run validate` — lint + filename checks; run before PRs.
+- `npm run size-check -w @frontjs/core` — ensure gzipped core stays under the 5KB budget.
+- `npm run docs:generate` / `npm run types:generate` — refresh API docs and d.ts outputs.
+
+## Coding Style & Naming Conventions
+- ES modules everywhere; 2-space indentation; prefer small, pure functions.
+- Keep public APIs documented with JSDoc; avoid implicit globals and side effects in module scope.
+- Filenames are lower-kebab-case; tests use `*.test.js`.
+- Security first: never use `eval`/`new Function`; sanitize/serialize via JSON only; respect Islands hydration model.
+
+## Testing Guidelines
+- Framework: Vitest (`jsdom`, globals enabled). Tests live in `tests/` and `packages/core/tests/`.
+- Naming: match subject (`reactivity.test.js`, `security.test.js`); colocate fixtures near suites.
+- Run `npm test` before pushing; add regression tests for every bug fix and new public API.
+- For manual verification, load `website/examples/index.html` via a static server to confirm hydration and XSS protections.
+
+## Commit & Pull Request Guidelines
+- Conventional Commits are expected (e.g., `feat(reactivity): add cleanup support`); keep scopes meaningful.
+- Branch names: `feat/<slug>`, `fix/<slug>`, `chore/<slug>`, etc., as in existing history.
+- PRs should describe motivation, testing performed (`npm test`, `npm run validate`, `npm run size-check -w @frontjs/core`), and link issues. Include screenshots/GIFs for UI-affecting changes in `website/` or examples.
+- Keep diffs minimal; update docs (`docs/`, `website/docs/`) and types when APIs change.

.github/workflows/ci.yml

@@ -2,9 +2,9 @@ name: Node.js CI
 
 on:
   push:
-    branches: [ "main", "master" ]
+    branches: [ "main" ]
   pull_request:
-    branches: [ "main", "master" ]
+    branches: [ "main" ]
 
 jobs:
   build:

.github/workflows/deploy-pages.yml

@@ -3,7 +3,7 @@ name: Deploy to GitHub Pages
 on:
   push:
     branches:
-      - master
+      - main
   workflow_dispatch:
 
 permissions:

.github/workflows/docs.yml

@@ -0,0 +1,52 @@
+name: Generate Documentation
+
+on:
+  push:
+    branches: [main, dev]
+    paths:
+      - 'packages/*/src/**/*.js'
+      - '.github/workflows/docs.yml'
+      - 'scripts/generate-api-docs.js'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  generate-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Generate API documentation
+        run: npm run docs:api
+
+      - name: Generate TypeScript definitions
+        run: npm run types:generate
+
+      - name: Check for changes
+        id: git-check
+        run: |
+          git diff --exit-code website/docs/api/ || echo "docs_changed=true" >> $GITHUB_OUTPUT
+          git diff --exit-code packages/*/types/ || echo "types_changed=true" >> $GITHUB_OUTPUT
+
+      - name: Commit updated docs
+        if: steps.git-check.outputs.docs_changed == 'true' || steps.git-check.outputs.types_changed == 'true'
+        run: |
+          git config user.name "frontjs-bot"
+          git config user.email "bot@frontjs.dev"
+          git add website/docs/api/ packages/*/types/ || true
+          git commit -m "docs: auto-generate API docs and TypeScript definitions [skip ci]" || exit 0
+          git push

.gitignore

@@ -3,6 +3,7 @@ node_modules/
 
 # Build outputs
 dist/
+types/
 *.map
 
 # Test coverage
@@ -54,3 +55,4 @@ pnpm-lock.yaml
 yarn.lock
 
 .agents/
+notes/

.husky/pre-commit

@@ -0,0 +1,5 @@
+# Validate documentation placement
+node scripts/validate-docs-placement.js
+
+# Run tests
+npm test

CLAUDE.md

@@ -9,6 +9,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 ## Key Commands
 
 ### Development
+
 ```bash
 npm install              # Install dependencies
 npm test                 # Run all tests with Vitest
@@ -20,11 +21,36 @@ npm run lint             # Lint code with ESLint
 ```
 
 ### Running Examples
+
 ```bash
 npx serve .
 # Navigate to http://localhost:3000/examples/index.html
 ```
 
+### Website Build Scripts (Optional)
+
+The framework itself has **zero build step**, but the website uses optional build scripts for progressive enhancement:
+
+```bash
+npm run navbar:generate  # Generate server-rendered navbar HTML
+npm run navbar:validate  # Validate navbar islands match config
+npm run docs:api         # Generate API documentation from JSDoc
+```
+
+**NavBar Generation**: Keeps server-rendered HTML in sync with props across all pages.
+
+- **Config**: `website/navbar-config.json` defines links for each page
+- **How it works**: Reads `NavBar.server.js` renderer → generates HTML → updates HTML files in-place
+- **Philosophy**: Generated HTML is committed to git (site works without building)
+- **When to use**: After editing navbar links or adding new pages with navbar
+
+To update navbar links:
+1. Edit `website/navbar-config.json`
+2. Run `npm run navbar:generate`
+3. Commit the updated HTML files
+
+**Why this works**: The framework ships as ES modules (no build). The website build is OPTIONAL and only for SEO/performance optimization (pre-rendering). This follows the same pattern as `generate-initial-doc.js` for docs.
+
 ## Architecture Overview
 
 ### Core Principles (see wiki/STANDARDS.md)
@@ -69,11 +95,13 @@ src/
 ### Hydration System (src/core/client.js)
 
 **Component Registration**:
+
 ```javascript
-register(name, componentFn)  // name must match /^[a-zA-Z0-9_-]+$/
+register(name, componentFn); // name must match /^[a-zA-Z0-9_-]+$/
 ```
 
 **Hydration Algorithm**:
+
 1. Query all `[data-island]` elements
 2. For each island:
    - Extract `data-component` name and validate (alphanumeric only)
@@ -88,6 +116,7 @@ register(name, componentFn)  // name must match /^[a-zA-Z0-9_-]+$/
 ### Component Model (src/core/component.js)
 
 Components are higher-order functions:
+
 ```javascript
 function MyComponent(props) {
   // Setup phase: create values, calculated values
@@ -101,6 +130,7 @@ function MyComponent(props) {
 `defineComponent(renderFn, container)` wraps the render function in a run that auto-reruns on value changes, passing the template to uhtml's render function for efficient DOM diffing.
 
 **Lifecycle Cleanup**: Components can use runs with cleanup functions for side effects:
+
 ```javascript
 function MyComponent(props) {
   const tick = val(0);
@@ -120,6 +150,7 @@ function MyComponent(props) {
 ## Critical Constraints
 
 ### Size Budget
+
 - **Hard limit**: <5KB minified + gzipped (excluding uhtml peer dependency)
 - Enforced via `npm run size-check` which fails CI if exceeded
 - Build config: `build.config.js` uses esbuild with target es2020
@@ -163,34 +194,34 @@ hydrate();
 ### Server-Rendered HTML
 
 ```html
-<div
-  data-island
-  data-component="Counter"
-  data-props='{"start": 10}'
-></div>
+<div data-island data-component="Counter" data-props='{"start": 10}'></div>
 ```
 
 ### Testing
 
 Tests use Vitest with jsdom environment. Key test files:
+
 - `tests/reactivity.test.js` - val/run/calc behavior
 - `tests/component.test.js` - Component lifecycle
 - `tests/client.test.js` - Hydration algorithm
 - `tests/security.test.js` - XSS protection, injection attacks
 
 Run single test file:
+
 ```bash
 npm test -- tests/reactivity.test.js
 ```
 
 ## Alignment with Standards
 
 When making changes, verify against:
+
 1. **docs/BLUEPRINT.md** - Detailed architecture and implementation specs
 2. **wiki/STANDARDS.md** - "North Star" principles (Headless Reactivity, Standard Schema alignment, Platform First)
 3. **wiki/PRD.md** - Original product requirements
 
 Major architectural changes require:
+
 1. Discussion in GitHub issue first
 2. Update to docs/BLUEPRINT.md
 3. Alignment with wiki/STANDARDS.md

CODE-OF-CONDUCT.md

@@ -17,23 +17,23 @@ diverse, inclusive, and healthy community.
 Examples of behavior that contributes to a positive environment for our
 community include:
 
-* Demonstrating empathy and kindness toward other people
-* Being respectful of differing opinions, viewpoints, and experiences
-* Giving and gracefully accepting constructive feedback
-* Accepting responsibility and apologizing to those affected by our mistakes,
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
   and learning from the experience
-* Focusing on what is best not just for us as individuals, but for the
+- Focusing on what is best not just for us as individuals, but for the
   overall community
 
 Examples of unacceptable behavior include:
 
-* The use of sexualized language or imagery, and sexual attention or
+- The use of sexualized language or imagery, and sexual attention or
   advances of any kind
-* Trolling, insulting or derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information, such as a physical or email
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email
   address, without their explicit permission
-* Other conduct which could reasonably be considered inappropriate in a
+- Other conduct which could reasonably be considered inappropriate in a
   professional setting
 
 ## Enforcement Responsibilities

CONTRIBUTING.md

@@ -13,28 +13,33 @@ We welcome contributions! Please read the [Blueprint](./docs/BLUEPRINT.md) and [
 ## Development Setup
 
 1. **Clone the repo:**
+
    ```bash
    git clone https://github.com/your-username/front-js.git
    cd front-js
    ```
 
 2. **Install dependencies:**
+
    ```bash
    npm install
    ```
 
 3. **Run examples:**
+
    ```bash
    npx serve .
    # Navigate to http://localhost:3000/examples/index.html
    ```
 
 4. **Build:**
+
    ```bash
    npm run build
    ```
 
 5. **Check bundle size:**
+
    ```bash
    npm run size-check
    ```
@@ -54,10 +59,11 @@ We welcome contributions! Please read the [Blueprint](./docs/BLUEPRINT.md) and [
    - [`wiki/PRD.md`](./wiki/PRD.md) - Product requirements
 
 2. **Create a feature branch:**
+
    ```bash
    git checkout -b feat/your-feature-name
    ```
-   
+
    **Branch Naming Convention:**
    - `feat/` - New features
    - `fix/` - Bug fixes
@@ -77,18 +83,20 @@ We welcome contributions! Please read the [Blueprint](./docs/BLUEPRINT.md) and [
    - Verify bundle size with `npm run size-check`
 
 5. **Format code:**
+
    ```bash
    npm run format
    ```
 
 6. **Commit with Conventional Commits:**
+
    ```bash
    # Format: <type>(<scope>): <subject>
    git commit -m "feat(reactivity): add cleanup support to run"
    git commit -m "fix(hydration): handle invalid JSON gracefully"
    git commit -m "docs(readme): add table of contents"
    ```
-   
+
    **Commit Types:**
    - `feat:` - New feature
    - `fix:` - Bug fix
@@ -154,12 +162,12 @@ npm run test:watch # Watch mode
 
 ## Pull Request Guidelines
 
-* **Follow the Blueprint:** Changes to the architecture must be discussed in `docs/BLUEPRINT.md` first.
-* **Keep it Dependency-Free:** Do not add NPM dependencies to the runtime. `uhtml` is the only allowed exception (peer dependency).
-* **Test Thoroughly:** Run tests and verify examples work.
-* **Check Size:** Ensure bundle size stays under 5KB.
-* **Update Docs:** Update wiki/API.md and README if adding/changing APIs.
-* **Security Review:** All changes are reviewed for security implications.
+- **Follow the Blueprint:** Changes to the architecture must be discussed in `docs/BLUEPRINT.md` first.
+- **Keep it Dependency-Free:** Do not add NPM dependencies to the runtime. `uhtml` is the only allowed exception (peer dependency).
+- **Test Thoroughly:** Run tests and verify examples work.
+- **Check Size:** Ensure bundle size stays under 5KB.
+- **Update Docs:** Update wiki/API.md and README if adding/changing APIs.
+- **Security Review:** All changes are reviewed for security implications.
 
 ## Architecture Decisions
 
@@ -174,4 +182,4 @@ Major architectural decisions should be:
 
 - Open an issue for bugs or feature requests
 - Check existing documentation first
-- Review the Blueprint for architecture questions
+- Review the Blueprint for architecture questions