Update readmes

Author: daniloc

README.md

@@ -112,7 +112,7 @@ Coming soon.
 
 Coming soon.
 
-## Getting Started
+## Getting started
 
 Each example includes its own README with setup instructions. Generally:
 
@@ -123,3 +123,48 @@ Each example includes its own README with setup instructions. Generally:
 
 See individual example READMEs for detailed instructions.
 
+## MCP manifest architecture
+
+This repository serves as the **single source of truth** for PostHog integration resources accessed via the [PostHog MCP server](https://github.com/PostHog/posthog/tree/main/products/mcp).
+
+### How it works
+
+1. **Build process** (`npm run build:docs`):
+   - Converts example projects to markdown
+   - Discovers workflow guides from `llm-prompts/`
+   - Discovers MCP prompts from `mcp-commands/`
+   - Generates `manifest.json` with all URIs and metadata
+   - Packages everything into `examples-mcp-resources.zip`
+
+2. **MCP server** (runtime):
+   - Fetches the ZIP from GitHub releases
+   - Loads `manifest.json`
+   - **Purely reflects** the manifest - no hardcoded URIs or logic
+
+### Manifest structure
+
+The manifest defines:
+- **Workflows**: Step-by-step guides with automatic next-step linking
+- **Docs**: PostHog documentation URLs
+- **Prompts**: MCP command prompts with template variable substitution
+- **Templates**: Resource templates for parameterized access (e.g., `posthog://examples/{framework}`)
+
+### Adding new resources
+
+**Workflows**: Add markdown files to `llm-prompts/[category]/` following the naming convention `[order].[step]-[name].md`
+
+**Examples**: Add new example projects to `basics/` and configure in `scripts/build-examples-mcp-resources.js`
+
+**Prompts**: Add JSON files to `mcp-commands/`
+
+The build script automatically discovers, orders, and generates URIs for all resources.
+
+### Why this architecture?
+
+- **Single source of truth**: All URIs defined in examples repo
+- **Zero hardcoding**: MCP server has no URIs or business logic
+- **Easy to extend**: Add resources by creating properly named files
+- **Version controlled**: Resources evolve with the examples
+
+See `llm-prompts/README.md` for detailed workflow conventions.
+

llm-prompts/README.md

@@ -1,21 +1,21 @@
-# LLM Prompts
+# LLM prompts
 
-This directory contains LLM workflow prompts that guide AI agents through various PostHog integration tasks.
+This directory contains LLM workflow prompts that guide AI agents through PostHog integration tasks.
 
 Feel free to try these out directly, or summon them from the PostHog MCP server. You can also use them as a starting point for your own deep integrations. We've tested these extensively.
 
 ## Structure
 
 - **basic-integration/**: Step-by-step workflow guides for adding PostHog event tracking to a project
-  - `1.0-event-setup-begin.md`: Initial project analysis and event planning
-  - `1.1-event-setup-edit.md`: Implementation guidance for adding PostHog tracking
-  - `1.2-event-setup-revise.md`: Error checking and correction
+  - `1.0-begin.md`: Initial project analysis and event planning
+  - `1.1-edit.md`: Implementation guidance for adding PostHog tracking
+  - `1.2-revise.md`: Error checking and correction
 
-## Manifest-Driven Architecture
+## Manifest-driven architecture
 
 These prompts and their URIs are defined in `manifest.json`, which is generated during the build process. The manifest is the **source of truth** for all resource URIs and metadata.
 
-### How It Works
+### How it works
 
 1. **Build time**: `scripts/build-examples-mcp-resources.js` generates:
    - `manifest.json` with all resource definitions and URIs
@@ -26,29 +26,29 @@ These prompts and their URIs are defined in `manifest.json`, which is generated
    - Loads `manifest.json`
    - **Purely reflects** the manifest - no URI generation, just registration
 
-### Manifest Structure
+### Manifest structure
 
 The manifest includes:
 - **Workflows**: Ordered sequence with `nextStepUri` for automatic linking
-- **Examples**: Pre-expanded list of framework-specific examples
-- **URIs**: Fully generated at build time (e.g., `posthog://workflows/basic-integration-begin`)
+- **Templates**: Resource templates for parameterized access (e.g., `posthog://examples/{framework}`)
+- **URIs**: Fully generated at build time (e.g., `posthog://workflows/basic-integration/begin`)
 
-### File Conventions
+### File conventions
 
 **Naming:** `[order].[step]-[name].md`
 
 Examples:
-- `1.0-event-setup-begin.md` → Order 1.0, step 0, ID: `basic-integration-event-setup-begin`
-- `1.1-event-setup-edit.md` → Order 1.1, step 1, ID: `basic-integration-event-setup-edit`
+- `1.0-begin.md` → Order 1.0, step 0, ID: `basic-integration-begin`
+- `1.1-edit.md` → Order 1.1, step 1, ID: `basic-integration-edit`
 - `2.0-analytics-setup.md` → Order 2.0, step 0, ID: `category-analytics-setup`
 
-**Required Frontmatter:**
+**Required frontmatter:**
 
 Every workflow file MUST include YAML frontmatter with `title` and `description`:
 
 ```markdown
 ---
-title: Event Setup - Begin
+title: PostHog setup - Begin
 description: Start the event tracking setup process by analyzing the project
 ---
 
@@ -59,21 +59,21 @@ The build will fail if frontmatter is missing or incomplete.
 
 **Automatic features:**
 - **Next step**: Automatically linked to the next file in numerical order
-- **URI generation**: `posthog://workflows/[category]-[name]`
+- **URI generation**: `posthog://workflows/[category]/[name]`
 
-### Adding New Workflows
+### Adding new workflows
 
 1. Create a new category directory: `llm-prompts/[category]/`
 2. Add markdown files following the naming convention
 3. Files are automatically:
    - Discovered and ordered
    - Linked to next steps
-   - Given URIs (e.g., `posthog://workflows/[category]-[name]`)
+   - Given URIs (e.g., `posthog://workflows/[category]/[name]`)
    - Added to the manifest
 
 **No configuration needed!** Just add properly named files.
 
-## Build Process
+## Build process
 
 These prompts are packaged into the release artifact `examples-mcp-resources.zip`.
 
@@ -85,9 +85,9 @@ npm run build:docs
 
 The MCP server fetches these prompts from the latest GitHub release and serves them as resources to AI agents and the PostHog wizard during integration tasks.
 
-## Architecture Benefits
+## Architecture benefits
 
 - **Single source of truth**: Examples repo controls all URIs
 - **No hardcoded URIs in MCP**: MCP purely reflects manifest
-- **Easy to extend**: Add resources by updating manifest config
+- **Easy to extend**: Add resources by creating properly named files
 - **Version controlled**: URIs and metadata evolve with the examples