more stuff

Author: MichaelYochpaz

.ai-workspace/README.md

@@ -1,189 +1,61 @@
 # AI Workspace Infrastructure
 
-This directory contains the infrastructure for the AI Workspace Template, including configuration management, scripts, and templates.
+This directory contains the infrastructure for the AI Workspace Template.
+
+**Full documentation:** [Configuration Reference](https://michaelyochpaz.github.io/ai-workspace-template/configuration/)
 
 ## Directory Structure
 
 ```
 .ai-workspace/
-├── lib/
-│   ├── __init__.py
-│   └── config.py              # Pydantic configuration models
-├── scripts/
-│   ├── align-workspace.py     # Pre-commit: aligns workspace with config
-│   ├── session-sync.py        # Session start: syncs submodules
-│   ├── transpile-skills.py
-│   ├── transpile-commands.py
-│   └── mktmpdir.py
-├── templates/
-│   ├── AGENTS.md.j2           # Jinja2 template for generating AGENTS.md
-│   ├── skills-readme.md       # Template for skills/README.md
-│   ├── commands-readme.md     # Template for commands/README.md
-│   └── agent-docs-readme.md   # Template for agent-docs/README.md
-├── zensical.toml              # Zensical documentation site config
-├── schema.json                # Auto-generated JSON schema for config
-└── README.md                  # This file
+├── docs/                  # Documentation source (Zensical site)
+├── lib/                   # Python library (config models)
+├── scripts/               # Automation scripts
+├── templates/             # Jinja2 templates
+├── schema.json            # JSON schema for ai-workspace.toml
+└── zensical.toml          # Documentation site config
 ```
 
-## AGENTS.md Generation
-
-`AGENTS.md` is **auto-generated** from the Jinja2 template at `.ai-workspace/templates/AGENTS.md.j2`. Do not edit it directly.
-
-### How It Works
+## Key Scripts
 
-1. The `align-workspace.py` script runs on every pre-commit
-2. It gathers data from:
-   - `ai-workspace.toml` (feature flags)
-   - `agent-docs/*/metadata.yaml` (documentation listings)
-   - `skills/` and `commands/` directories (item counts)
-   - `AGENTS.project.md` (project-specific content)
-3. It renders the template and writes `AGENTS.md`
+| Script | Purpose |
+|--------|---------|
+| `align-workspace.py` | Pre-commit: regenerates AGENTS.md, manages feature dirs |
+| `session-sync.py` | Session start: syncs submodules, discovers tools |
+| `transpile-skills.py` | Validates and distributes skills |
+| `transpile-commands.py` | Validates and distributes commands |
+| `mktmpdir.py` | Creates unique task directories under `.tmp/` |
 
-### Project-Specific Instructions
+## AGENTS.md Generation
 
-Add project-specific instructions in `AGENTS.project.md` at the repository root. This content is merged into the generated `AGENTS.md`.
+`AGENTS.md` is auto-generated from `templates/AGENTS.md.j2`. Don't edit directly.
 
-**Initial state:** The file ships with `<placeholder>` tags. Remove these tags when adding your content:
+- **Workspace instructions:** Edit `templates/AGENTS.md.j2`
+- **Project-specific instructions:** Edit `AGENTS.project.md` at repo root
 
-```markdown
-<placeholder>
-Add project-specific instructions here...
-</placeholder>
+Regenerate manually:
+```bash
+uv run .ai-workspace/scripts/align-workspace.py
 ```
 
-**Detection logic:**
-- If file is missing → project section omitted
-- If file contains `<placeholder>` → project section omitted
-- If file has content (no `<placeholder>`) → content included in AGENTS.md
-
-### Conditional Sections
-
-The template conditionally includes sections based on configuration and content:
-
-| Section | Included When |
-|---------|---------------|
-| Agent Docs | `features.agent_docs = true` |
-| Commands | `features.commands = true` AND commands exist |
-| Skills | `features.skills = true` AND skills exist |
-| Project Content | `AGENTS.project.md` has content (no `<placeholder>`) |
-
 ## Configuration
 
-The workspace is configured via `ai-workspace.toml` at the repository root.
-
-### Schema
-
-The `schema.json` file provides JSON Schema for editor autocomplete. It's auto-generated from the Pydantic models in `lib/config.py`.
-
-### Configuration Reference
-
-#### `[workspace]`
-
-| Key | Type | Default | Description |
-|-----|------|---------|-------------|
-| `name` | string | `"AI Workspace"` | Workspace display name |
+The workspace is configured via `ai-workspace.toml` at the repository root. Key sections:
 
-#### `[sync]`
+| Section | Purpose |
+|---------|---------|
+| `[workspace]` | General settings (name) |
+| `[repositories]` | Repository status and sync settings |
+| `[hooks.session_start]` | Session start script config |
+| `[features]` | Enable/disable skills, commands, agent-docs |
+| `[tools]` | Tool discovery settings |
+| `[distribution]` | Where to distribute skills/commands |
 
-| Key | Type | Default | Description |
-|-----|------|---------|-------------|
-| `skip_on_uncommitted_changes` | bool | `true` | Skip submodules with uncommitted changes (`false` = fail) |
-| `default_branch` | string | `"main"` | Fallback branch if not specified in .gitmodules |
-| `template_upstream_url` | string | (template URL) | URL for template update notifications. Set empty to disable. |
-| `template_upstream_git_remote` | string | `"template-upstream"` | Git remote name for the template upstream |
-
-#### `[hooks.session_start]`
-
-| Key | Type | Default | Description |
-|-----|------|---------|-------------|
-| `script` | string | (required) | Path to the script to run at session start |
-| `timeout` | int | `120` | Timeout in seconds |
-
-#### `[features]`
-
-| Key | Type | Default | Description |
-|-----|------|---------|-------------|
-| `skills` | bool | `true` | Enable skills system |
-| `commands` | bool | `true` | Enable commands system |
-| `agent_docs` | bool | `true` | Enable agent-docs system |
-
-**Warning:** Disabling a feature removes its directory if empty. If the directory has user content, pre-commit will fail with instructions to manually remove the content.
-
-#### `[distribution]`
-
-| Key | Type | Default | Description |
-|-----|------|---------|-------------|
-| `skills_paths` | list[str] | `[".opencode/skill"]` | Target directories for skills symlinks |
-| `commands_paths` | list[str] | (IDE dirs) | Target directories for commands |
-
-**Note:** `.cursor/*` paths automatically use `strip_frontmatter` method; all others use symlinks.
-
-### Example Configuration
-
-```toml
-[workspace]
-name = "AI Workspace"
-
-[sync]
-skip_on_uncommitted_changes = true
-default_branch = "main"
-template_upstream_url = "https://github.com/MichaelYochpaz/ai-workspace-template.git"
-template_upstream_git_remote = "template-upstream"
-
-[hooks.session_start]
-script = ".ai-workspace/scripts/session-sync.py"
-timeout = 120
-
-[features]
-skills = true
-commands = true
-agent_docs = true
-
-[distribution]
-skills_paths = [".opencode/skill"]
-commands_paths = [
-    ".roo/commands",
-    ".claude/commands",
-    ".cursor/commands",
-    ".opencode/command",
-]
-```
+See [Configuration](https://michaelyochpaz.github.io/ai-workspace-template/configuration/) for the full reference.
 
-## Scripts
+## Documentation Site
 
-### align-workspace.py
-
-Runs via pre-commit. Ensures workspace state matches `ai-workspace.toml`:
-
-- Manages feature directories (creates/removes based on config)
-- Generates `AGENTS.md` from Jinja2 template
-- Generates `.claude/settings.json` with SessionStart hooks
-- Ensures `.opencode/plugins/` directory exists for OpenCode plugin
-- Updates `schema.json` from Pydantic models
-- Runs feature-specific validators (skills, commands)
-
-### session-sync.py
-
-Runs at AI tool session start. Syncs submodules to their configured branches:
-
-- Reads branch configuration from `.gitmodules`
-- Skips submodules with uncommitted changes (configurable)
-- Checks for template updates and displays notification
-- Non-blocking: network failures don't prevent session start
-
-### transpile-skills.py / transpile-commands.py
-
-Validate and distribute skills/commands to IDE-specific directories. See `skills/README.md` and `commands/README.md` for details.
-
-### mktmpdir.py
-
-Creates unique task directories under `.tmp/` for organizing temporary files.
-
-## Tool Configurations
-
-### Documentation Site
-
-The documentation site is built with [Zensical](https://zensical.org/) and configured via `zensical.toml` in this directory. Build and preview commands:
+Built with [Zensical](https://zensical.org/). Config in `zensical.toml`.
 
 ```bash
 # Preview locally
@@ -192,67 +64,3 @@ zensical serve --config-file .ai-workspace/zensical.toml
 # Build static site
 zensical build --config-file .ai-workspace/zensical.toml
 ```
-
-### Claude Code
-
-The align-workspace script generates `.claude/settings.json` with a SessionStart hook:
-
-```json
-{
-  "hooks": {
-    "SessionStart": [
-      {
-        "matcher": "startup|resume",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "uv run \"$CLAUDE_PROJECT_DIR/.ai-workspace/scripts/session-sync.py\"",
-            "timeout": 120,
-            "statusMessage": "Syncing submodules..."
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
-### OpenCode
-
-The `.opencode/plugins/session-sync.ts` plugin reads configuration from `ai-workspace.toml` at runtime:
-
-- Listens for `session.created` events
-- Reads `hooks.session_start.script` from `ai-workspace.toml`
-- Executes the configured script via `uv run`
-- Injects results into the system prompt via `experimental.chat.system.transform` hook
-
-## Extending
-
-### Adding a New Hook Type
-
-1. Add the hook config to `lib/config.py` (HooksConfig class)
-2. Update `align-workspace.py` to generate tool-specific configurations
-3. Regenerate schema: `uv run .ai-workspace/scripts/align-workspace.py`
-
-### Adding a New IDE/Tool
-
-1. Update `transpile-skills.py` and/or `transpile-commands.py` with new IDE config
-2. Add hook generation to `align-workspace.py` if the tool supports session hooks
-3. Update `[distribution]` defaults in `lib/config.py`
-
-### Modifying AGENTS.md Structure
-
-Edit the Jinja2 template at `.ai-workspace/templates/AGENTS.md.j2`. The template receives:
-
-```python
-{
-    "features": {
-        "agent_docs": {"enabled": bool, "docs": [AgentDoc, ...]},
-        "skills": {"enabled": bool, "count": int},
-        "commands": {"enabled": bool, "count": int},
-    },
-    "project_content": str | None,
-}
-```
-
-Run `uv run .ai-workspace/scripts/align-workspace.py` to regenerate AGENTS.md after template changes.