|
| 1 | +# Plugin Source Contract — Naming Conventions |
| 2 | + |
| 3 | +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. |
| 4 | + |
| 5 | +## Reference File Structure |
| 6 | + |
| 7 | +Reference files in the plugin repo are organized by app_type: |
| 8 | + |
| 9 | +``` |
| 10 | +plugins/gcore-fastedge/skills/ |
| 11 | + scaffold/reference/ |
| 12 | + http/ # HTTP app blueprints |
| 13 | + base-rust.md # Base skeleton |
| 14 | + kv-store-rust.md # Feature blueprint |
| 15 | + cdn/ # CDN app blueprints |
| 16 | + base-rust.md # Base skeleton |
| 17 | + body-rust.md # Feature blueprint |
| 18 | + fastedge-docs/reference/ |
| 19 | + http/ # HTTP app example patterns |
| 20 | + examples-kv-store-rust.md |
| 21 | + cdn/ # CDN app example patterns |
| 22 | + examples-body-rust.md |
| 23 | + sdk-reference-rust.md # Cross-cutting (no subfolder) |
| 24 | + host-services-rust.md # Cross-cutting (no subfolder) |
| 25 | + cdn-apps-rust.md # Cross-cutting app-type guide (no subfolder) |
| 26 | +``` |
| 27 | + |
| 28 | +Note: `http/base-rust.md` and `cdn/base-rust.md` have the same filename but live in different subfolders. The pipeline's path-based intent matching resolves them to different intent files. |
| 29 | + |
| 30 | +## File Naming Convention |
| 31 | + |
| 32 | +**`{concept}-{lang}.md`** — concept first, language last. The subfolder provides the app_type context. |
| 33 | + |
| 34 | +| Type | Pattern | Example | |
| 35 | +|---|---|---| |
| 36 | +| Base skeleton | `{appType}/base-{lang}.md` | `http/base-rust.md`, `cdn/base-rust.md` | |
| 37 | +| Feature blueprint | `{appType}/{concept}-{lang}.md` | `cdn/body-rust.md` | |
| 38 | +| Docs pattern | `{appType}/examples-{concept}-{lang}.md` | `cdn/examples-body-rust.md` | |
| 39 | +| Cross-cutting SDK ref | `sdk-reference-{lang}.md` | `sdk-reference-rust.md` | |
| 40 | +| Cross-cutting host services | `host-services-{lang}.md` | `host-services-rust.md` | |
| 41 | +| Cross-cutting app-type guide | `{appType}-apps-{lang}.md` | `cdn-apps-rust.md` | |
| 42 | + |
| 43 | +## Manifest target_mapping Rules |
| 44 | + |
| 45 | +1. **reference_file** paths must include the `http/` or `cdn/` subfolder for per-example content (blueprints and patterns). Cross-cutting references (`sdk-reference`, `host-services`, `cdn-apps`) live directly under `fastedge-docs/reference/` with no subfolder |
| 46 | +2. **section** should be `null` for all entries (each file is owned by one repo — no splicing) |
| 47 | +3. **Dual-intent pattern**: each **feature** example gets two entries with the same `files` array: |
| 48 | + - `{name}-blueprint` → `scaffold/reference/{appType}/{concept}-{lang}.md` |
| 49 | + - `{name}-pattern` → `fastedge-docs/reference/{appType}/examples-{concept}-{lang}.md` |
| 50 | + |
| 51 | + **Exception**: Base skeleton examples (`http-hello-world`, `cdn-hello-world`) only get a `-blueprint` entry pointing to `scaffold/reference/{appType}/base-{lang}.md`. They have no `-pattern` counterpart because they don't demonstrate a reusable feature pattern. |
| 52 | + |
| 53 | +## Intent File Matching |
| 54 | + |
| 55 | +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. |
| 56 | + |
| 57 | +Example: |
| 58 | +- `reference_file`: `plugins/.../scaffold/reference/cdn/body-rust.md` |
| 59 | +- Path suffix: `cdn/body-rust.md` |
| 60 | +- Intent lookup: `agent-intent-skills/fastedge-sdk-rust/cdn/body-rust.md` |
| 61 | + |
| 62 | +This is why `http/base-rust.md` and `cdn/base-rust.md` can coexist — they resolve to `agent-intent-skills/fastedge-sdk-rust/http/base-rust.md` and `agent-intent-skills/fastedge-sdk-rust/cdn/base-rust.md` respectively. |
| 63 | + |
| 64 | +## When Adding New Examples |
| 65 | + |
| 66 | +1. Add source entries (paired `-blueprint` and `-pattern` for feature examples; `-blueprint` only for base skeletons) to `manifest.json` |
| 67 | +2. Add target_mapping entries pointing to `{appType}/{concept}-{lang}.md` paths |
| 68 | +3. Request intent files be created in `fastedge-plugin` repo (or create via PR): |
| 69 | + - `agent-intent-skills/fastedge-sdk-rust/{appType}/{concept}-{lang}.md` (scaffold) |
| 70 | + - `agent-intent-skills/fastedge-sdk-rust/{appType}/examples-{concept}-{lang}.md` (docs) |
| 71 | + - Each should reference `../_scaffold-blueprint-base.md` or `../_docs-pattern-base.md` |
| 72 | +4. Create placeholder reference files at the target paths in the plugin repo |
0 commit comments