update manifest naming convention

context/CONTEXT_INDEX.md

@@ -36,6 +36,13 @@
 |----------|-------|---------|
 | `PROJECT_OVERVIEW.md` | ~150 | Lightweight project overview — architecture, key modules, dev setup, common commands. Read when new to the codebase. |
 | `CHANGELOG.md` | ~25+ | Change history. Use grep, don't read linearly as this file grows. |
+| `ENHANCEMENTS.md` | ~50 | Known inconsistencies and planned improvements. Read before refactoring related areas. |
+
+### Plugin Integration (read when modifying manifest or examples)
+
+| Document | Lines | Purpose |
+|----------|-------|---------|
+| `PLUGIN_CONTRACT.md` | ~70 | Naming conventions, manifest rules, intent file matching for the fastedge-plugin sync pipeline. Read when adding examples to `manifest.json` or changing `fastedge-plugin-source/`. |
 
 ### External (not in context/)
 
@@ -83,6 +90,7 @@
 4. **Every example MUST have its own `README.md`** explaining what it does
 5. **Every example MUST have an entry in `examples/README.md`** (the top-level index)
 6. **Terminology**: In READMEs, always refer to "environment variables" — never "dictionary variables". `dictionary` is the internal package name for accessing environment variables, not a user-facing concept
+7. **Plugin sync**: If this example should feed into fastedge-plugin, read `context/PLUGIN_CONTRACT.md` for manifest and naming conventions
 
 ### Changing the Build System
 1. Read `development/BUILD_SYSTEM.md`

context/ENHANCEMENTS.md

@@ -0,0 +1,53 @@
+# Enhancements & Known Issues
+
+Tracked improvements that don't warrant external issues. Check items off or remove them as they're resolved.
+
+---
+
+## Config Schema: `ignoreDirs` vs `ignorePaths` inconsistency
+
+**Status:** Open
+**Identified:** 2026-04-08 (during plugin reference doc review)
+**Affects:** `fastedge-init` scaffolder, `fastedge-build` static pipeline
+
+### Problem
+
+The init wizard (`src/cli/fastedge-init/create-config.ts`) generates static build configs using `ignoreDirs`:
+
+```js
+// What fastedge-init writes to .fastedge/build-config.js
+{
+  type: "static",
+  ignoreDirs: ["./node_modules"]
+}
+```
+
+But the formal `AssetCacheConfig` type (`src/server/static-assets/asset-manifest/types.ts`) defines `ignorePaths` and `assetManifestPath`:
+
+```ts
+interface AssetCacheConfig {
+  assetManifestPath: string;
+  ignorePaths: string[];
+  // ...
+}
+```
+
+The build pipeline silently accepts both — `create-manifest-file-map.ts` merges `ignoreDirs` and `ignorePaths` into one array. But this means:
+
+1. Configs generated by `fastedge-init` use a field name (`ignoreDirs`) not present in the formal type
+2. `assetManifestPath` is required in `AssetCacheConfig` but never emitted by `fastedge-init`
+3. Docs for each tool are accurate to their respective source, but contradict each other
+
+### Suggested Fix
+
+Either:
+- **Option A:** Update `create-config.ts` to emit `ignorePaths` + `assetManifestPath` (align init output with the formal type)
+- **Option B:** Add `ignoreDirs` as an explicit field in `AssetCacheConfig` and make `assetManifestPath` optional
+
+Option A is cleaner — one canonical field name, init output matches the type system.
+
+### Files Involved
+
+- `src/cli/fastedge-init/create-config.ts` — generates the config (uses `ignoreDirs`)
+- `src/server/static-assets/asset-manifest/types.ts` — defines `AssetCacheConfig` (uses `ignorePaths`)
+- `src/server/static-assets/asset-manifest/create-manifest-file-map.ts` — consumes both (merges them)

context/PLUGIN_CONTRACT.md

@@ -0,0 +1,60 @@
+# Plugin Source Contract — Naming Conventions
+
+This document describes the naming and structure conventions for `manifest.json` in this repo. These rules ensure the sync-reference-docs pipeline correctly maps source files to plugin reference docs and intent skills.
+
+## Reference File Structure
+
+Reference files in the plugin repo are organized by app_type:
+
+```
+plugins/gcore-fastedge/skills/
+  scaffold/reference/
+    http/                     # HTTP app blueprints
+      base-ts.md              # Base skeleton
+      kv-store-ts.md          # Feature blueprint
+    cdn/                      # CDN app blueprints (future)
+    build-cli.md              # Cross-cutting (no subfolder)
+  fastedge-docs/reference/
+    http/                     # HTTP app example patterns
+      examples-kv-store-js.md
+    cdn/                      # CDN app example patterns (future)
+    sdk-reference-js.md       # Cross-cutting (no subfolder)
+```
+
+## File Naming Convention
+
+**`{concept}-{lang}.md`** — concept first, language last. The subfolder provides the app_type context.
+
+| Type | Pattern | Example |
+|---|---|---|
+| Base skeleton | `{appType}/base-{lang}.md` | `http/base-ts.md` |
+| Feature blueprint | `{appType}/{concept}-{lang}.md` | `http/kv-store-ts.md` |
+| Docs pattern | `{appType}/examples-{concept}-{lang}.md` | `http/examples-kv-store-js.md` |
+| Cross-cutting SDK ref | `sdk-reference-{lang}.md` | `sdk-reference-js.md` |
+
+## Manifest target_mapping Rules
+
+1. **reference_file** paths must include the `http/` or `cdn/` subfolder for app_type-specific content
+2. **section** should be `null` for all entries (each file is owned by one repo — no splicing)
+3. **Dual-intent pattern**: each example gets two entries with the same `files` array:
+   - `{name}-blueprint` → `scaffold/reference/{appType}/{concept}-{lang}.md`
+   - `{name}-pattern` → `fastedge-docs/reference/{appType}/examples-{concept}-{lang}.md`
+
+## Intent File Matching
+
+The pipeline resolves intent files by extracting the path suffix after `reference/` from the `reference_file` path. It looks for that same relative path inside the plugin's intent directory for this repo.
+
+Example:
+- `reference_file`: `plugins/.../scaffold/reference/http/kv-store-ts.md`
+- Path suffix: `http/kv-store-ts.md`
+- Intent lookup: `agent-intent-skills/fastedge-sdk-js/http/kv-store-ts.md`
+
+## When Adding New Examples
+
+1. Add source entries (paired `-blueprint` and `-pattern`) to `manifest.json`
+2. Add target_mapping entries pointing to `{appType}/{concept}-{lang}.md` paths
+3. Request intent files be created in `fastedge-plugin` repo (or create via PR):
+   - `agent-intent-skills/fastedge-sdk-js/{appType}/{concept}-{lang}.md` (scaffold)
+   - `agent-intent-skills/fastedge-sdk-js/{appType}/examples-{concept}-{lang}.md` (docs)
+   - Each should reference `../_scaffold-blueprint-base.md` or `../_docs-pattern-base.md`
+4. Create placeholder reference files at the target paths in the plugin repo

fastedge-plugin-source/manifest.json

@@ -140,7 +140,7 @@
   },
   "target_mapping": {
     "sdk-api": {
-      "reference_file": "plugins/gcore-fastedge/skills/fastedge-docs/reference/sdk-reference.md",
+      "reference_file": "plugins/gcore-fastedge/skills/fastedge-docs/reference/sdk-reference-js.md",
       "section": null
     },
     "build-cli": {
@@ -161,52 +161,52 @@
     },
 
     "hello-world-blueprint": {
-      "reference_file": "plugins/gcore-fastedge/skills/scaffold/reference/base-http-ts.md",
+      "reference_file": "plugins/gcore-fastedge/skills/scaffold/reference/http/base-ts.md",
       "section": null
     },
 
     "kv-store-blueprint": {
-      "reference_file": "plugins/gcore-fastedge/skills/scaffold/reference/http-ts-kv-store.md",
+      "reference_file": "plugins/gcore-fastedge/skills/scaffold/reference/http/kv-store-ts.md",
       "section": null
     },
     "kv-store-pattern": {
-      "reference_file": "plugins/gcore-fastedge/skills/fastedge-docs/reference/examples-kv-store.md",
+      "reference_file": "plugins/gcore-fastedge/skills/fastedge-docs/reference/http/examples-kv-store-js.md",
       "section": null
     },
 
     "ab-testing-blueprint": {
-      "reference_file": "plugins/gcore-fastedge/skills/scaffold/reference/http-ts-ab-testing.md",
+      "reference_file": "plugins/gcore-fastedge/skills/scaffold/reference/http/ab-testing-ts.md",
       "section": null
     },
     "ab-testing-pattern": {
-      "reference_file": "plugins/gcore-fastedge/skills/fastedge-docs/reference/examples-ab-testing.md",
+      "reference_file": "plugins/gcore-fastedge/skills/fastedge-docs/reference/http/examples-ab-testing-js.md",
       "section": null
     },
 
     "fetch-blueprint": {
-      "reference_file": "plugins/gcore-fastedge/skills/scaffold/reference/http-ts-fetch.md",
+      "reference_file": "plugins/gcore-fastedge/skills/scaffold/reference/http/fetch-ts.md",
       "section": null
     },
     "fetch-pattern": {
-      "reference_file": "plugins/gcore-fastedge/skills/fastedge-docs/reference/examples-fetch.md",
+      "reference_file": "plugins/gcore-fastedge/skills/fastedge-docs/reference/http/examples-fetch-js.md",
       "section": null
     },
 
     "headers-blueprint": {
-      "reference_file": "plugins/gcore-fastedge/skills/scaffold/reference/http-ts-headers.md",
+      "reference_file": "plugins/gcore-fastedge/skills/scaffold/reference/http/headers-ts.md",
       "section": null
     },
     "headers-pattern": {
-      "reference_file": "plugins/gcore-fastedge/skills/fastedge-docs/reference/examples-headers.md",
+      "reference_file": "plugins/gcore-fastedge/skills/fastedge-docs/reference/http/examples-headers-js.md",
       "section": null
     },
 
     "geo-redirect-blueprint": {
-      "reference_file": "plugins/gcore-fastedge/skills/scaffold/reference/http-ts-geo-redirect.md",
+      "reference_file": "plugins/gcore-fastedge/skills/scaffold/reference/http/geo-redirect-ts.md",
       "section": null
     },
     "geo-redirect-pattern": {
-      "reference_file": "plugins/gcore-fastedge/skills/fastedge-docs/reference/examples-geo-redirect.md",
+      "reference_file": "plugins/gcore-fastedge/skills/fastedge-docs/reference/http/examples-geo-redirect-js.md",
       "section": null
     }
   },