docs: clarify substrate extension types (markdown vs code)

PHILOSOPHY.md

@@ -73,6 +73,17 @@ The corollary: things like hosted search, MCP servers, and automation pipelines
 
 When in doubt: if it requires code to run, it's not substrate. It belongs in the intelligence layer.
 
+### Two types of extension
+
+This boundary clarifies what kind of extension you're building:
+
+| Type | What it is | How it installs | Lives where |
+|------|-----------|-----------------|-------------|
+| **Markdown extension** | Instructions, templates, prompts — things the AI reads and acts on | Point your AI at a link. No CLI, no npm. | In the substrate (your repo) |
+| **Code extension** | A worker, webhook receiver, or automation that runs outside the repo and writes files into it | Deploy the code separately (Cloudflare Worker, GitHub Action, Railway service) | In the intelligence layer, above the substrate |
+
+A markdown extension adds behavior without adding runtime. A code extension adds runtime — and that runtime lives outside the repo by design. Both are valid. They serve different purposes and install differently because they are different things.
+
 ---
 
 ## The Evolution Principle

_meta/instructions/agent-write.md

@@ -18,6 +18,18 @@ This protocol ensures that all agent-written files are:
 
 ---
 
+## Content-Type Routing
+
+When creating specific content types, use the dedicated template and follow the corresponding instructions:
+
+| Content Type | Template | Instructions |
+|-------------|----------|-------------|
+| Blog post | `_meta/templates/blog-post.md` | `_meta/instructions/blog-posts/instructions.md` |
+
+For blog posts: copy the template, fill out the Visual Plan **before** writing the draft, and follow the publishing flow in the instructions.
+
+---
+
 ## The Golden Rule: Inbox First
 
 When capturing something new, it goes to `_inbox/` first — not directly to a final location. This keeps agent writes auditable and gives the user the chance to review before content becomes part of the system.

_meta/instructions/blog-posts/instructions.md

@@ -0,0 +1,89 @@
+---
+type: instruction
+summary: How to create blog posts using the standard template and publishing flow.
+tags: [meta, publishing]
+status: active
+updated: 2026-04-12
+---
+
+# Blog Post Instructions
+
+## Template
+
+Use `_meta/templates/blog-post.md` for all blog posts. Copy it to the appropriate location (typically `5-Publishing/` or wherever the user's publishing folder lives) and fill in each section.
+
+---
+
+## Visual Plan (Required)
+
+Every blog post must have a Visual Plan section filled out **before** writing the full draft. The plan ensures posts are scannable and engaging.
+
+**Minimum:** 2-3 visual elements per post, chosen from:
+
+- **Code / data blocks** — real examples, not hypothetical. Readers skim for code.
+- **Tables** — comparisons, summaries, before/after. Use when prose would repeat a pattern.
+- **Screenshots** — annotated where possible. Every screenshot requires:
+  - **Placement** — where it goes relative to the text
+  - **Alt text** — accessible description for screen readers
+  - **Caption** — contextual label for sighted readers
+- **Pull quotes** — highlight a key insight or provocative claim. Use sparingly.
+
+If a post has zero visual elements, push back and ask what could be added.
+
+---
+
+## SEO Keywords
+
+Keywords should be **problem-first, not product-first**.
+
+Good: `automate deployment pipeline`, `reduce CI build time`
+Bad: `MyTool features`, `MyTool deployment`
+
+Think about what someone would search for when they have the problem your post solves. Put yourself in the reader's shoes before they know your solution exists.
+
+Place 3-5 keywords in the frontmatter `seo_keywords` field.
+
+---
+
+## Publishing Flow
+
+1. **Draft** — Write in the template. Fill out the Visual Plan first, then the Full Draft.
+2. **Review** — Self-review or peer review. Check that:
+   - Visual Plan elements are all present in the draft
+   - Screenshots have alt text and captions
+   - SEO keywords appear naturally in the text
+   - The Social Post section is ready to copy-paste
+3. **Publish** — Post to the primary platform. Update `status: published` and the `updated` date in frontmatter.
+4. **Cross-post** — Adapt for secondary platforms (newsletter, social, etc.). Use the Social Post section as the starting point.
+5. **Track** — Update the post file with the published URL and any cross-post links.
+
+---
+
+## Screenshot Requirements
+
+Screenshots are not optional decoration. Every screenshot must be intentional:
+
+- **Placement** must be specified (e.g., "after the setup section", "before the results table")
+- **Alt text** must describe what the screenshot shows, not just "screenshot of the UI"
+- **Caption** must give context a reader needs — what should they notice?
+
+If a screenshot doesn't have all three, it's not ready.
+
+---
+
+## The P.S. Convention
+
+If something notable happened during the writing process — an unexpected discovery, a tangent that deserves its own post, a process observation — capture it in the P.S. section at the bottom.
+
+This is optional but encouraged. It adds a human touch and can seed future content.
+
+---
+
+## File Naming
+
+Blog post files should follow the standard:
+```
+YYYY-MM-DD-short-description.md
+```
+
+Example: `2026-04-12-visual-planning-for-blog-posts.md`

_meta/templates/blog-post.md

@@ -0,0 +1,53 @@
+---
+type: blog-post
+summary: "[One sentence: what does this post teach or argue?]"
+tags: [blog, domain]  # replace domain with real tags
+seo_keywords: [keyword-1, keyword-2, keyword-3]  # problem-first, not product-first
+substack_tags: [tag-1, tag-2]  # platform-specific tags for cross-posting
+status: draft
+updated: YYYY-MM-DD
+---
+
+# [Title — clear, specific, searchable]
+
+## Social Post
+
+[1-3 sentences for sharing on social media. Hook + key takeaway + link placeholder.]
+
+---
+
+## Visual Plan
+
+> Every post needs 2-3 visual elements. Plan them before writing the draft.
+
+### Code / Data Blocks
+
+- [ ] [Description of code snippet or data example]
+- [ ] [Description of code snippet or data example]
+
+### Tables
+
+- [ ] [Description of table and what it compares or summarizes]
+
+### Screenshots
+
+| Screenshot | Placement | Alt Text | Caption |
+|------------|-----------|----------|---------|
+| [Description] | [Before/after which section] | [Accessible description] | [Caption for readers] |
+| [Description] | [Before/after which section] | [Accessible description] | [Caption for readers] |
+
+### Pull Quotes
+
+- [ ] "[Key quote or callout to highlight]"
+
+---
+
+## Full Draft
+
+[Write the post here. Reference visual elements from the plan above by placement.]
+
+---
+
+## P.S.
+
+[Optional. If something meta happened during writing — an insight, a tangent, a process note — capture it here.]

docs/extending-and-contributing.md

@@ -24,6 +24,16 @@ Structural patterns that help everyone:
 - Obsidian configurations or plugin recommendations that enhance the wiki pattern
 - Bug fixes where instructions don't work well with a particular LLM
 
+## Two Kinds of Extension
+
+Before building an extension, know which kind it is — they install differently and live in different places.
+
+**Markdown extension** — instructions, templates, or prompts that the AI reads and implements in your repo. No code required. You install it by pointing your AI at a link or copying files into your repo. Examples: a new template type, a custom instruction module, a domain-specific prompt library.
+
+**Code extension** — a worker, webhook receiver, or automation that runs *outside* the repo and writes files into it. It requires deployment (Cloudflare Worker, GitHub Action, Railway service, etc.). Examples: an Omi integration that commits voice memos to `_inbox/`, a social monitor that files daily reports, a webhook that routes emails into structured notes.
+
+The rule: if it requires code to run, it's a code extension and belongs in the intelligence layer above the substrate — not in the repo itself.
+
 ## The Litmus Test
 
 If your change requires knowing what *your* wiki is about, it's an extension. If it works regardless of domain, it's a contribution.