Feature/agent skills

.agents/README.md

@@ -6,18 +6,27 @@ Project-local skills for Cursor agents working on this repository.
 
 ```
 .agents/skills/<skill-name>/SKILL.md
+.cursor/rules/*.mdc          # always-on / scoped project rules
 ```
 
-Each skill teaches the agent domain-specific workflows for Fusion (Rust core + Python / Node / C# bindings).
+Each skill teaches domain-specific workflows for Fusion (Rust core + Python / Node / C# bindings) and the companion `fusion` CLI.
 
 ## Available skills
 
 | Skill | Use when |
 |-------|----------|
-| `fusion-architecture` | Understanding repo layout, binding layers, where logic belongs |
-| `fusion-bindings-parity` | Changing behavior that must stay aligned across Python, Node, C# |
-| `fusion-http-routes` | Routes, `@http_get` / `[HttpGet]`, `[module]`, `[action]`, Swagger |
+| `fusion-architecture` | Repo layout, binding layers, where logic belongs |
+| `fusion-bindings-parity` | Feature must land in Python **and** Node **and** C# |
+| `fusion-coding-standards` | Comments, tests preference, git staging, skill/doc hygiene |
+| `fusion-cli` | `fusion init` / commands / scaffold tree / CLI ↔ framework |
+| `fusion-http-routes` | Routes, `http_get` / `[HttpGet]`, `[module]`, `[action]`, Swagger |
 | `fusion-release` | Version bumps, manifests, publish prep |
-| `fusion-testing` | Running checks and binding-specific tests |
+| `fusion-testing` | Running checks; investigating failed tests |
 
-Skills are loaded when the task matches the skill description (or when you name the skill explicitly).
+## Always-on rules
+
+`.cursor/rules/fusion-engineering.mdc` applies every session: parity across bindings, **examples in all three languages for new features**, function comments, prefer tests, never `git add .`, investigate failures, update skills when needed.
+
+## Hygiene
+
+When you add a new concept agents must remember, either extend an existing skill or add `.agents/skills/<name>/SKILL.md` and a row in this table.

.agents/skills/fusion-architecture/SKILL.md

@@ -1,9 +1,10 @@
 ---
 name: fusion-architecture
 description: >-
-  Explains Fusion Framework repository layout, crate boundaries, and where
-  new logic belongs (fusion-core vs Python/Node/C# bindings). Use when
-  navigating the codebase, adding features, or deciding which layer to change.
+  Explains Fusion Framework repository layout, crate boundaries, where new
+  logic belongs (fusion-core vs Python/Node/C# bindings), tests layout, and
+  relationship to the fusion CLI. Use when navigating the codebase, adding
+  features, or deciding which layer to change.
 ---
 
 # Fusion Architecture
@@ -12,18 +13,24 @@ description: >-
 
 | Path | Role |
 |------|------|
-| `crates/fusion-core/` | Shared Rust: naming, route tokens, HTTP conventions |
+| `crates/fusion-core/` | Shared Rust: naming, route tokens, HTTP conventions, settings helpers |
 | `crates/fusion-py/` | Python binding (PyO3) + `python/fusion_framework/` package |
 | `crates/fusion-node/` | Node binding (`index.js`, N-API) |
-| `bindings/csharp/FusionFramework/` | C# binding (source of truth for NuGet layout) |
+| `crates/fusion-ffi/` | C ABI for the C# binding |
+| `bindings/csharp/FusionFramework/` | C# binding (NuGet layout source of truth) |
+| `tests/` | Executable tests (Python / Node / C#) — not inside installable packages |
 | `examples/` | Runnable samples per binding |
-| `scripts/` | Release tooling (`set-version.sh`) |
+| `scripts/` | Dev install, version bumps (`set-version.sh`) |
+| `.agents/skills/` | Agent skills for this repo |
+
+**Related external repo:** [fusion-tool](https://github.com/cipherunits/fusion-tool) — `fusion` CLI that scaffolds apps. See `fusion-cli` skill.
 
 ## Layering rules
 
 1. **Put shared semantics in `fusion-core`** — route token resolution (`[module]`, `[action]`), path joining, handler naming. Bindings should call Rust helpers via FFI where possible.
 2. **Bindings mirror behavior** — Python decorators, Node functions, C# attributes must produce the same mount paths and OpenAPI shapes.
 3. **Do not duplicate business logic in three languages** — only binding-specific glue (decorators, reflection, module registration).
+4. **Tests live under `tests/`** — do not add `test_*.py` inside `fusion_framework/` package sources.
 
 ## Key entry points
 
@@ -33,6 +40,9 @@ description: >-
 
 ## When adding a feature
 
-1. Identify if it is cross-binding (yes → start in `fusion-core`).
-2. Implement mount + OpenAPI in all three bindings in one PR when possible.
-3. Add or extend an example under `examples/`.
+1. Identify if it is cross-binding (yes → start in `fusion-core` when semantics are shared).
+2. Implement in **Python, Node, and C#** in one change set (see `fusion-bindings-parity`).
+3. Add tests under `tests/` (preferred) and/or Rust unit tests.
+4. Add **usage examples in all three languages** under `examples/` (`<feature>.py` / `.mjs` / `.cs`) so the API shape is visible.
+5. If scaffolds or env JSON contracts change, update the `fusion-cli` skill and consider fusion-tool templates.
+6. Comment new functions; document dense logic (see `fusion-coding-standards`).

.agents/skills/fusion-bindings-parity/SKILL.md

@@ -2,20 +2,39 @@
 name: fusion-bindings-parity
 description: >-
   Keeps Python, Node, and C# Fusion bindings aligned when changing APIs, routes,
-  Swagger, or middleware. Use when editing more than one binding or adding
-  cross-language behavior.
+  Swagger, middleware, or permissions. Use when editing more than one binding
+  or when the user asks to add a feature (always implement all three languages
+  unless they limit scope).
 ---
 
 # Bindings Parity
 
+## Hard rule
+
+If the user says “add X” (permissions, middleware, route option, Swagger behavior, settings key, etc.) and X is framework surface area, implement it for:
+
+1. **Python**
+2. **Node**
+3. **C#**
+
+in the **same** change set unless they explicitly say “only Python” (or only one binding).
+
+Do not leave one language behind “for later” without saying so and getting confirmation.
+
 ## Checklist (every cross-binding change)
 
 - [ ] `fusion-core` updated if semantics are shared
-- [ ] Python: `fusion_framework/` + `crates/fusion-py/src/api_types.rs`
-- [ ] Node: `crates/fusion-node/index.js`
+- [ ] Python: `fusion_framework/` + `crates/fusion-py/src/api_types.rs` as needed
+- [ ] Node: `crates/fusion-node/index.js` (+ `index.d.ts` if public types change)
 - [ ] C#: `bindings/csharp/FusionFramework/*.cs`
-- [ ] Example snippet in `examples/` (at least one runnable file + others documented)
+- [ ] Tests under `tests/python/`, `tests/node/`, and/or `tests/csharp/` when behavior is testable
+- [ ] **Examples in all three languages** under `examples/` (`<feature>.py`, `<feature>.mjs`, `<feature>.cs`) showing how to use the new API
 - [ ] README in C# binding updated if public API changed
+- [ ] Skills/docs updated if agents need new knowledge (`fusion-cli`, `fusion-http-routes`, …)
+
+## Examples rule
+
+New public surface → show usage in **Python + Node + C#**. Prefer the same basename for the trio (see `custom_http_routes.*`, `pagination.*`). Examples should be short and runnable enough to see the API shape, not full apps.
 
 ## Parity matrix
 
@@ -24,8 +43,11 @@ description: >-
 | Module route | `@route("/api/[module]")` | `route('/api/[module]')(Cls)` | `[Route("/api/[module]")]` |
 | Convention HTTP | `def get(self)` | `get()` method | `Get()` method |
 | Custom HTTP | `@http_get("path/[action]")` | `httpGet('path/[action]')(proto.method)` | `[HttpGet("path/[action]")]` |
+| Middleware | `middleware.py` factories | factories in `index.js` | `Middleware.cs` |
+| Permissions | `permissions=` / `require_permissions` | `permissions` / `requirePermissions` | `PermissionTypes` / `RequirePermissions` |
 | OpenAPI / Swagger | `app.py` + `api_types.rs` | `buildOpenApi` in `index.js` | `Swagger.cs` |
 | Version navbar | per-version OpenAPI routes | same | same |
+| Template routes | omit from OpenAPI | omit | omit |
 
 ## Verification commands
 
@@ -34,10 +56,13 @@ cargo test -p fusion-core naming
 cargo check -p fusion-py
 node --check crates/fusion-node/index.js
 dotnet build bindings/csharp/FusionFramework/FusionFramework.csproj
-python -m pytest crates/fusion-py/python/fusion_framework/test_http_route.py -q
+./tests/scripts/run-python.sh -q
+./tests/scripts/run-node.sh
+./tests/scripts/run-csharp.sh -q
 ```
 
 ## Style
 
 - Match existing naming in each language (snake_case Python, camelCase Node helpers, PascalCase C#).
 - Prefer minimal diffs; do not refactor unrelated binding code.
+- Comment new exported helpers (see `fusion-coding-standards`).

.agents/skills/fusion-cli/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: fusion-cli
+description: >-
+  Documents the Fusion Tool CLI (fusion init, command, module, add, update),
+  the scaffolded project tree, and how the CLI relates to this framework repo.
+  Use when explaining project layout, scaffolding, env JSON, or when framework
+  API changes must stay compatible with fusion-tool generators.
+---
+
+# Fusion CLI (fusion-tool)
+
+Apps are usually created with **Fusion Tool** (`fusion`), a separate repo:
+https://github.com/cipherunits/fusion-tool
+
+This skill describes the CLI from the **framework** side so agents know what
+generated projects look like and what must stay compatible.
+
+## Install & entry
+
+```bash
+fusion --help
+fusion --version
+```
+
+Binary name: `fusion`. Source of truth for generators: `fusion-tool` (`src/command/`, `src/setting/structure.rs`, `src/setting/environment.rs`).
+
+## Commands overview
+
+| Command | Purpose |
+|---------|---------|
+| `fusion init` | Scaffold a new Fusion app (Python / TypeScript / ASP.NET Core) |
+| `fusion command <name>` | Run a named command from `fusion.<env>.json` |
+| `fusion load-env` | Load `fusion.<env>.json` into the process environment |
+| `fusion module init` | Scaffold a **publishable library package** (not an app route module) |
+| `fusion add --github OWNER/REPO` | Vendor a module into the current app |
+| `fusion update` | Self-update the CLI binary |
+
+### `fusion init`
+
+```bash
+fusion init
+fusion init my-app
+fusion init --lang python --name myproject --description "…"
+```
+
+| Flag / arg | Values |
+|------------|--------|
+| `[DIRECTORY]` | Target dir (created if missing; default = cwd) |
+| `--lang` | `python`, `typescript`, `asp-core` |
+| `--name` | Project name |
+| `--description` | Short description |
+
+Writes `fusion-framework.toml`, `fusion.{dev,stage,prod}.json`, `.gitignore`, language entrypoint, sample route module, templates, and dependency pins to the framework version.
+
+### `fusion command`
+
+Commands live under the `commands` object in `fusion.<env>.json`.
+
+```bash
+fusion command run                 # default env: FUSION_ENV or `dev`
+fusion command run --stage
+fusion command run:stage           # same
+fusion command run --prod
+fusion command run --env test
+fusion command --stage             # list commands for that env
+```
+
+Runs via the shell from the project root with `FUSION_ENV` set so `core/settings` loads the matching file.
+
+### Modules vs route modules
+
+| Term | Meaning |
+|------|---------|
+| Route module | App code: `FusionBaseApi` / template under `src/modules/…` |
+| Library module | Separate package from `fusion module init` (`fusion.module.toml`), installed with `fusion add` |
+
+Do not confuse the two when naming APIs or writing docs.
+
+### `fusion module init` / `fusion add`
+
+```bash
+fusion module init --lang python --name example --description "…"
+fusion add --github OWNER/MODULE_NAME
+fusion add --github OWNER/MODULE_NAME@v1.0.0
+```
+
+Vendors under `.fusion/modules/<id>/` and records `[[modules]]` in `fusion-framework.toml`.
+
+## Scaffolded app layout (`fusion init`)
+
+Python shown; TypeScript/C# use the same tree with language extensions.
+
+```text
+<project>/
+├── core/
+│   └── settings.py          # Overlay (RELOAD, TEMPLATES_DIR, …)
+├── src/
+│   └── modules/
+│       └── products/
+│           └── products.py  # HomePage (template) + ProductModule (API)
+├── templates/
+│   └── home/
+│       ├── index.html
+│       └── style.css
+├── main.py                  # Register middleware + FusionApp.listen()
+├── requirements.txt         # Python pin (or package.json / *.csproj)
+├── pyproject.toml           # Python only
+├── fusion-framework.toml    # Project metadata + tool/framework versions
+├── fusion.dev.json          # env=dev, port 8080, swagger on, reload
+├── fusion.stage.json        # port 8081
+├── fusion.prod.json         # port 9090
+└── .gitignore
+```
+
+TypeScript: `main.ts`, `core/settings.ts`, `package.json`, `tsconfig.json`.  
+C# (`asp-core`): `main.cs`, `*.csproj` (`net10.0`), `[Route]` / `[HttpGet]`.
+
+### What the starter demonstrates
+
+- `FusionBaseTemplate` at `/` (Tera templates; **not** listed in Swagger).
+- `FusionBaseApi` at `api/[module]` with `version="v1"` → `/v1/api/product/…`.
+- Convention verbs (`get` / `post` / …) plus one custom slot (`http_get` / `httpGet` / `[HttpGet]` with `[action]`).
+- Opt-in middleware list in `main` (e.g. `request_id`, `cors`, `cache_headers`, `security_headers`, `framework_headers`). Framework does **not** auto-enable middleware; the scaffold opts in.
+
+### Default ports
+
+| Env | Port |
+|-----|------|
+| dev | 8080 |
+| stage | 8081 |
+| prod | 9090 |
+
+### Environment JSON shape
+
+```json
+{
+  "env": "dev",
+  "config": {
+    "host": "127.0.0.1",
+    "port": 8080,
+    "debug": true,
+    "fingerprint": { "enabled": false },
+    "swagger": { "enabled": true, "path": "/swagger" }
+  },
+  "commands": {
+    "run": "python main.py"
+  }
+}
+```
+
+`FUSION_ENV` selects `fusion.<env>.json` (default `dev`). Unresolved `HOST` placeholders must not crash listen — framework resolves safe defaults.
+
+## Compatibility duties (framework ↔ CLI)
+
+When changing public Fusion APIs used by scaffolds:
+
+1. Prefer keeping generated starter patterns working (or update **fusion-tool** templates in a follow-up / paired PR).
+2. Do not invent decorators/config keys that only exist in one binding.
+3. After middleware / route / settings changes, check whether `fusion-tool` `structure.rs` / `environment.rs` comments or defaults need updates.
+4. Version pin in the CLI (`FUSION_FRAMEWORK_VERSION`) is separate from this repo’s version bump (`./scripts/set-version.sh`).
+
+## Related
+
+- Framework layout: `fusion-architecture`
+- Binding alignment: `fusion-bindings-parity`
+- Routes: `fusion-http-routes`
+- CLI repo skills (if editing the tool itself): fusion-tool `.agents/skills/fusion-cli*`