@tangle-network/starter-foundry 0.5.4 → 0.7.2

package/registry/layers/framework/sglang-server/manifest.json

@@ -0,0 +1,62 @@
+{
+  "id": "sglang-server",
+  "description": "Python scaffold for SGLang inference — src/ package with OpenAI-compatible client, pyproject.toml with type-checker config, and Makefile targets for install / typecheck / run.",
+  "appliesTo": ["sglang-server"],
+  "files": [
+    { "source": "files/README.md", "target": "README.md" },
+    { "source": "files/__init__.py", "target": "src/__init__.py" },
+    { "source": "files/pyproject.toml", "target": "pyproject.toml" },
+    { "source": "files/Makefile", "target": "Makefile" }
+  ],
+  "buildHints": {
+    "whenToUse": "This layer supplies the Python project wrapper for the SGLang family — pyproject.toml metadata, a type-checker baseline, and a Makefile so developers can run common tasks without looking up flags.",
+    "firstSteps": [
+      "pip install -r requirements.txt          # install client deps",
+      "pip install -e '.[dev]'                   # install pyright + ruff",
+      "make typecheck                            # pyright src/ — should be clean",
+      "cp .env.example .env && make up          # start the Docker inference server",
+      "make client                               # python -m src.client (server must be running)"
+    ],
+    "gotchas": [
+      "pyproject.toml sets typeCheckingMode=basic; tighten to strict only after adding py.typed and full annotations throughout src/.",
+      "The Makefile uses hard tabs — editors that silently convert to spaces will break make. Most editors detect Makefile type and preserve tabs.",
+      "`pip install -e '.[dev]'` requires pyproject.toml to be present (supplied by this layer); running it before layer application will fail.",
+      "pyright is a dev-only dep; the runtime server has no Python typechecker dependency — requirements.txt stays lean."
+    ],
+    "architectureNotes": [
+      "src/__init__.py makes src/ a proper package so `python -m src.client` resolves without a separate __main__.py.",
+      "pyproject.toml is the single source of truth for Python version, project name, and dev-tool configuration — requirements.txt is kept as a flat pip-installable subset for Docker and CI."
+    ],
+    "placeholders": [
+      {
+        "path": "pyproject.toml",
+        "description": "project.name is 'starter-sglang' — rename to match your actual project before publishing to PyPI or internal package registries."
+      }
+    ]
+  },
+  "contextHints": {
+    "commands": [
+      "pip install -r requirements.txt",
+      "pip install -e '.[dev]'",
+      "make typecheck",
+      "make lint",
+      "make client",
+      "make up",
+      "make logs"
+    ],
+    "entrypoints": [
+      "src/client.py",
+      "src/__init__.py"
+    ],
+    "preview": {
+      "path": "/health",
+      "port": "30000"
+    },
+    "extensionPoints": [
+      "src/client.py",
+      "src/__init__.py",
+      "pyproject.toml",
+      "Makefile"
+    ]
+  }
+}

package/registry/layers/framework/skypilot-serving/files/AGENTS.md

@@ -0,0 +1,85 @@
+# AGENTS.md — SkyPilot LLM Serving
+
+Multi-cloud LLM inference endpoint managed by SkyPilot. `sky serve up` provisions
+GPU replicas across AWS/GCP/Azure/Kubernetes, auto-picks the cheapest region, handles
+spot preemption, and load-balances across replicas. vLLM runs the model on each replica.
+
+## File map
+
+| File | Purpose |
+|------|---------|
+| `service.yaml` | **Primary config.** GPU type, model ID, replica count, spot flag, vLLM startup command. Edit this first. |
+| `sky-serve.yaml` | Controller + load-balancer policy (round-robin, auto-scale rules). Most projects leave this unchanged. |
+| `requirements.txt` | SkyPilot + httpx. Run `pip install -r requirements.txt` before any `sky` commands. |
+| `.env.example` | Copy to `.env`. Set `HF_TOKEN` for gated models. |
+| `validate-skypilot.mjs` | Structural validator — runs locally, no cloud credentials needed. |
+| `README.md` | Operator guide with full deploy/teardown workflow. |
+
+## Placeholders that must be filled before deploying
+
+All `{{token}}` strings in the scaffold are intentional template tokens:
+
+| Token | File(s) | Replace with |
+|-------|---------|--------------|
+| `{{modelId}}` | service.yaml, .env.example | HuggingFace model ID, e.g. `meta-llama/Meta-Llama-3.1-8B-Instruct` |
+| `{{acceleratorSpec}}` | service.yaml, .env.example | SkyPilot GPU string: `A100:1`, `A100-80GB:1`, `H100:1`, `L4:1` |
+| `{{endpointName}}` | README.md, .env.example | Your service name, e.g. `my-llm` |
+| `{{port}}` | service.yaml | Port the inference server binds to — default `8000` |
+
+## Validation (no cloud needed)
+
+```bash
+node validate-skypilot.mjs   # must print: skypilot starter ok
+```
+
+If it fails, the output names the missing token or file.
+
+## Install and cloud check
+
+```bash
+pip install -r requirements.txt
+
+# Authenticate with at least one cloud:
+aws configure              # AWS
+gcloud auth login          # GCP
+kubectl config current-context  # Kubernetes
+
+sky check                  # must show ≥1 enabled cloud before deploying
+```
+
+## Deploy / operate / tear down
+
+```bash
+# Deploy (pass --env HF_TOKEN=... for gated models)
+sky serve up -n <endpointName> service.yaml
+
+# Check replica status — wait for READY (3-10 min cold start)
+sky serve status <endpointName>
+
+# Tail replica logs
+sky serve logs <endpointName> --target replica 1
+
+# Hit the endpoint (SkyPilot prints the URL once READY)
+ENDPOINT=$(sky serve status <endpointName> --endpoint)
+curl "$ENDPOINT/v1/chat/completions" \
+  -H 'Content-Type: application/json' \
+  -d '{"model": "<modelId>", "messages": [{"role":"user","content":"hello"}]}'
+
+# Tear down — ALWAYS run this when done. You are billed while replicas run.
+sky serve down <endpointName>
+```
+
+## What to customize
+
+- **Model**: Edit `MODEL_ID` in `service.yaml` under `envs:`, or override at launch with `--env MODEL_ID=...`.
+- **GPU type**: Edit `accelerators:` in `service.yaml`. SkyPilot picks the cheapest region offering that GPU.
+- **Spot savings**: Set `use_spot: true` for 50-80% cost reduction. Tune `readiness_probe.initial_delay_seconds` to your model's actual cold-start time.
+- **Replicas**: Change `replicas:` in `service.yaml`. Increase for higher throughput; SkyPilot load-balances automatically.
+- **Inference engine**: The `run:` block defaults to vLLM. Replace it with TGI, SGLang, Triton, or a custom FastAPI server — keep the port open and the readiness probe valid.
+
+## Cost safety rules
+
+1. `sky serve down <endpointName>` must be run after every test/demo — replicas bill by the hour.
+2. The controller VM runs 24/7 (~$30/mo on AWS). Leave it running across services; tearing it down and up costs more than keeping it live.
+3. Add `sky serve down` to any CI teardown step for review environments.
+4. For large models (>7B), add `file_mounts` with S3/GCS weight caching before scaling to multiple replicas — each spawn re-downloads weights without it.

package/registry/layers/framework/skypilot-serving/manifest.json

@@ -0,0 +1,68 @@
+{
+  "id": "skypilot-serving",
+  "description": "SkyPilot multi-cloud LLM serving — sky serve up provisions GPU replicas across AWS/GCP/Azure/Kubernetes, auto-picks cheapest region, handles spot preemption, and load-balances across replicas. vLLM runs the model on each replica behind a managed endpoint.",
+  "appliesTo": ["skypilot-serving"],
+  "files": [
+    { "source": "files/AGENTS.md", "target": "AGENTS.md" }
+  ],
+  "buildHints": {
+    "whenToUse": "Pick SkyPilot when you need multi-cloud LLM inference, spot-GPU cost savings, or automatic failover across cloud regions. For single-host or single-cloud deployments, use vllm-server or tgi-server directly — SkyPilot adds value only when multi-cloud orchestration or spot preemption handling matters.",
+    "firstSteps": [
+      "pip install -r requirements.txt",
+      "Authenticate with at least one cloud: `aws configure` / `gcloud auth login` / `kubectl config` — then run `sky check` to confirm ≥1 cloud is enabled.",
+      "Edit service.yaml: set resources.accelerators (e.g. A100:1), envs.MODEL_ID (e.g. meta-llama/Meta-Llama-3.1-8B-Instruct), and replicas.",
+      "sky serve up -n <endpointName> service.yaml   — pass --env HF_TOKEN=$HF_TOKEN for gated models.",
+      "sky serve status <endpointName> — wait for replica READY (3-10 min cold start), then hit the printed endpoint URL.",
+      "sky serve down <endpointName> when done — you are billed while replicas run."
+    ],
+    "gotchas": [
+      "`sky serve up` starts billing immediately. `sky serve down` is not optional — add a teardown step to any CI/review pipeline.",
+      "Accelerator strings are SkyPilot-specific: A100:1, A100-80GB:1, H100:1, L4:1. Cloud instance names (p4d.24xlarge) go under resources.instance_type, not accelerators.",
+      "use_spot: true saves 50-80% but spot preemption restarts replicas. Tune readiness_probe.initial_delay_seconds for your model's cold-start time; the default 600s is intentionally conservative.",
+      "First `sky serve up` provisions a controller VM (~$30/mo on AWS). Leave it running — it coordinates all your services and restarting it is slower and pricier than keeping it live.",
+      "Large model weights re-download on every replica spawn unless you add file_mounts pointing to an S3/GCS bucket. For models >7B parameters, set up weight caching before scaling to multiple replicas.",
+      "Kubernetes backend: `sky check kubernetes` must succeed BEFORE `sky serve up` — otherwise SkyPilot silently falls back to the first configured cloud."
+    ],
+    "architectureNotes": [
+      "service.yaml is the replica spec — describes what runs on each GPU VM. sky-serve.yaml is the controller config — load-balancer policy, replica scaling, controller sizing. Edit service.yaml first; most teams never touch sky-serve.yaml.",
+      "SkyPilot is the orchestrator; vLLM is the default inference engine. Swap the run: block to use TGI, SGLang, Triton, or a custom FastAPI app. SkyPilot only requires an open port and a passing readiness probe.",
+      "The readiness probe hits /v1/models. Any OpenAI-compatible server that responds to that path qualifies as ready."
+    ],
+    "placeholders": [
+      {
+        "path": "service.yaml",
+        "description": "{{modelId}} — HuggingFace model ID (e.g. meta-llama/Meta-Llama-3.1-8B-Instruct). {{acceleratorSpec}} — GPU spec (A100:1, H100:1, L4:1). {{port}} — port the inference server binds to (default 8000)."
+      },
+      {
+        "path": ".env.example",
+        "description": "{{modelId}} — HuggingFace model ID. {{acceleratorSpec}} — GPU spec. {{endpointName}} — SkyPilot service name. Also set HF_TOKEN to your HuggingFace token for gated models before deploying."
+      },
+      {
+        "path": "README.md",
+        "description": "{{endpointName}} — SkyPilot service name used in all sky serve commands. {{modelId}} — HuggingFace model ID shown in the example curl call."
+      }
+    ]
+  },
+  "contextHints": {
+    "commands": [
+      "pip install -r requirements.txt",
+      "sky check",
+      "sky serve up -n <endpointName> service.yaml",
+      "sky serve status <endpointName>",
+      "sky serve logs <endpointName> --target replica 1",
+      "sky serve down <endpointName>",
+      "node validate-skypilot.mjs"
+    ],
+    "entrypoints": [
+      "AGENTS.md",
+      "service.yaml",
+      "sky-serve.yaml",
+      "README.md"
+    ],
+    "preview": null,
+    "extensionPoints": [
+      "service.yaml",
+      "sky-serve.yaml"
+    ]
+  }
+}

package/registry/layers/framework/soc2-compliance-pack/files/AGENTS.md

@@ -0,0 +1,46 @@
+# SOC2 Compliance Pack — Agent Guide
+
+## What this pack provides
+- **`src/audit.ts`** — `InMemorySocAuditStore` + types. Swap for a DB-backed store in production.
+- **`src/change-mgmt.ts`** — `recordChange()`: enforces CC8.1 (≥1 approver, no self-approval).
+- **`src/index.ts`** — re-exports everything; import from here.
+- **`docs/SOC2-controls.md`** — Trust Services Criteria CC1–CC9 mapped to files.
+- **`docs/vendor-attestations.md`** — Live sub-processor registry; update quarterly.
+- **`docs/incident-response.md`** — CC7.3 playbook; run a tabletop exercise before audit.
+
+## First steps
+
+```bash
+pnpm install
+pnpm build          # tsc --noEmit — must pass with zero errors
+node validate-soc2-pack.mjs   # smoke-checks required files + logic
+```
+
+## Integration pattern
+
+```typescript
+import { InMemorySocAuditStore, recordChange } from './src/index.js'
+
+const store = new InMemorySocAuditStore()
+
+await recordChange(store, {
+  id: 'chg-001',
+  title: 'Enable feature flag X',
+  description: 'Roll out to 10% of users',
+  requester: 'alice@example.com',
+  approvers: ['bob@example.com'],          // CC8.1: must have ≥1, not self
+  target: 'application',
+  requestedAt: new Date().toISOString(),
+})
+```
+
+## Key compliance rules
+- Audit log retention: 12 months minimum (confirm with auditor; some require 7 years).
+- Change management (CC8.1): no self-merges. Enforce via branch protection, not policy alone.
+- Vendor attestations must be current within the audit window (not older than ~1 year).
+- Incident response (CC7.3): run at least one tabletop exercise before audit.
+
+## Extending
+- Replace `InMemorySocAuditStore` with a Postgres/SQLite implementation for persistence.
+- Add a `SocAuditMiddleware` to auto-log HTTP mutations (POST/PUT/DELETE).
+- Hook `recordChange()` into your CI deploy pipeline to capture every production change.

package/registry/layers/framework/soc2-compliance-pack/files/README.md

@@ -0,0 +1,61 @@
+# SOC2 Compliance Pack
+
+Node/TypeScript primitives for SOC2 Type II audit evidence: append-only audit log (CC7.2), change-management approvals (CC8.1), vendor attestation registry (CC9.1), and incident-response playbook (CC7.3).
+
+## Quick start
+
+```bash
+pnpm install
+pnpm build                    # tsc --noEmit — must pass with zero errors
+node validate-soc2-pack.mjs   # smoke-checks required files and logic
+```
+
+## What's included
+
+| File | Purpose |
+|---|---|
+| `src/audit.ts` | `SocAuditStore` interface + `InMemorySocAuditStore` drop-in |
+| `src/change-mgmt.ts` | `recordChange()` — enforces CC8.1 (≥1 approver, no self-approval) |
+| `src/index.ts` | Re-exports everything; import from here |
+| `docs/SOC2-controls.md` | Trust Services Criteria CC1–CC9 mapped to files |
+| `docs/vendor-attestations.md` | Sub-processor registry — update quarterly |
+| `docs/incident-response.md` | CC7.3 playbook — run a tabletop before audit |
+
+## Integration
+
+```typescript
+import { InMemorySocAuditStore, recordChange } from './src/index.js'
+
+const store = new InMemorySocAuditStore()
+
+await recordChange(store, {
+  id: 'chg-001',
+  title: 'Enable feature flag X',
+  description: 'Roll out to 10% of users',
+  requester: 'alice@example.com',
+  approvers: ['bob@example.com'],   // CC8.1: ≥1 approver, not self
+  target: 'application',
+  requestedAt: new Date().toISOString(),
+})
+
+await store.append({
+  at: new Date().toISOString(),
+  actor: 'deploy-bot',
+  action: 'deploy',
+  target: 'production:v1.2.3',
+  approvedBy: ['bob@example.com'],
+})
+```
+
+## Before your audit
+
+1. Replace `InMemorySocAuditStore` with a DB-backed implementation — audit logs must survive restarts and be append-only at the DB level (revoke `UPDATE`/`DELETE` on the table from the app user).
+2. Fill in `docs/vendor-attestations.md` with every sub-processor and their current SOC2 report date.
+3. Enable GitHub branch protection + `CODEOWNERS` to enforce the ≥1-approver requirement at the SCM level (CC8.1).
+4. Run at least one tabletop incident-response exercise and record it in `docs/tabletop-log.md` (CC7.3 evidence).
+
+## Key constraints
+
+- Audit log retention: 12 months minimum; confirm with your auditor (some require 7 years).
+- Change approvals: self-approval is rejected by `recordChange()` — also enforce at the PR level.
+- Vendor attestations must be current within the audit window (not older than ~12 months).

package/registry/layers/framework/soc2-compliance-pack/files/src/index.ts

@@ -0,0 +1,3 @@
+// Main entrypoint — re-exports all SOC2 Type II compliance primitives.
+export * from './audit.js'
+export * from './change-mgmt.js'

package/registry/layers/framework/soc2-compliance-pack/manifest.json

@@ -0,0 +1,52 @@
+{
+  "id": "soc2-compliance-pack",
+  "description": "SOC2 Type II compliance framework layer — append-only audit log, change-management approvals (CC8.1), vendor registry, and incident-response playbook. Composes onto any Node/TypeScript backend.",
+  "appliesTo": ["soc2-compliance-pack"],
+  "files": [
+    { "source": "files/README.md", "target": "README.md" },
+    { "source": "files/src/index.ts", "target": "src/index.ts" },
+    { "source": "files/AGENTS.md", "target": "AGENTS.md" }
+  ],
+  "packageDeps": {
+    "devDependencies": {
+      "typescript": "^5.9.0",
+      "@types/node": "^22.0.0"
+    }
+  },
+  "buildHints": {
+    "whenToUse": "Bolt SOC2 Type II primitives (audit trail, change-management approvals, vendor registry) onto an existing Node/TypeScript backend before a Type II audit window opens.",
+    "firstSteps": [
+      "Run `pnpm install` then `pnpm build` (`tsc --noEmit`) — must pass with zero errors.",
+      "Run `node validate-soc2-pack.mjs` to confirm required files and logic are present.",
+      "Wire `recordChange()` from `src/change-mgmt.ts` onto every deploy and config change — CC8.1 requires change approvals to be logged.",
+      "Replace `InMemorySocAuditStore` with a DB-backed implementation before going to production (audit logs must persist across restarts).",
+      "Fill in `docs/vendor-attestations.md` with every sub-processor (Stripe, AWS, Vercel, etc.) and their SOC2 report links."
+    ],
+    "gotchas": [
+      "Audit log retention for SOC2 is commonly 12 months minimum; some auditors require 7 years. Confirm before TTL-ing old rows.",
+      "Change management (CC8.1) requires ≥1 approver per change — self-merges are flagged. Enforce via branch protection, not honor system.",
+      "Vendor attestations must be CURRENT (within the audit window). A 2-year-old vendor SOC2 report is an exception finding.",
+      "Incident response (CC7.3) needs a tested playbook. Run at least one tabletop exercise before the audit."
+    ],
+    "architectureNotes": [
+      "SOC2 audits are about process evidence, not code. This pack produces the artifacts (audit rows, CODEOWNERS, playbooks) auditors want to see. The controls themselves are operational.",
+      "`InMemorySocAuditStore` is intentionally a drop-in; swap it for a Postgres/SQLite implementation by implementing the `SocAuditStore` interface."
+    ],
+    "placeholders": [
+      {
+        "path": "docs/SOC2-controls.md",
+        "description": "Trust Services Criteria CC1–CC9 mapped to files. Customize the scope section per your actual audit."
+      },
+      {
+        "path": "docs/vendor-attestations.md",
+        "description": "Live sub-processor registry. Add every vendor with a SOC2 report and update at least quarterly."
+      }
+    ]
+  },
+  "contextHints": {
+    "commands": ["pnpm install", "pnpm build", "node validate-soc2-pack.mjs"],
+    "entrypoints": ["src/index.ts"],
+    "preview": null,
+    "extensionPoints": ["src/audit.ts", "src/change-mgmt.ts", "docs/SOC2-controls.md", "docs/vendor-attestations.md"]
+  }
+}

package/registry/layers/framework/sp1-zkvm/manifest.json

@@ -0,0 +1,6 @@
+{
+  "id": "sp1-zkvm",
+  "description": "Framework layer for sp1-zkvm — content ships from the family scaffold (registry/families/sp1-zkvm/files/). This layer is the scaffold declaration that selectStarter emits.",
+  "appliesTo": ["sp1-zkvm"],
+  "files": []
+}

package/registry/layers/framework/stm32-rust/files/.cargo/config.toml

@@ -0,0 +1,9 @@
+[build]
+target = "thumbv7em-none-eabihf"
+
+[target.thumbv7em-none-eabihf]
+runner = "probe-rs run --chip STM32F411RETx"
+rustflags = [
+  "-C", "link-arg=-Tlink.x",
+  "-C", "link-arg=-Tdefmt.x",
+]

package/registry/layers/framework/stm32-rust/files/Embed.toml

@@ -0,0 +1,27 @@
+# probe-rs configuration. `cargo embed` reads this for target + RTT config.
+[default.probe]
+# Auto-select the first attached probe. Pin a `usb_vid = "xxxx"` /
+# `usb_pid = "yyyy"` here if the board has a specific ST-Link / CMSIS-DAP.
+protocol = "Swd"
+speed = 4000
+
+[default.general]
+chip = "STM32F411RETx"
+# Override per-board:
+# - Nucleo-F411RE: STM32F411RETx
+# - Nucleo-F401RE: STM32F401RETx
+# - STM32F4-Discovery: STM32F407VGTx
+# - Black Pill: STM32F411CEUx
+
+[default.rtt]
+enabled = true
+up_mode = "NoBlockSkip"
+channels = [{ up = 0, down = 0, name = "defmt" }]
+
+[default.gdb]
+enabled = false
+
+[default.flashing]
+enabled = true
+restore_unwritten_bytes = false
+halt_afterwards = false

package/registry/layers/framework/stm32-rust/files/rust-toolchain.toml

@@ -0,0 +1,3 @@
+[toolchain]
+channel = "stable"
+targets = ["thumbv7em-none-eabihf"]

package/registry/layers/framework/stm32-rust/files/src/main.rs

@@ -0,0 +1,54 @@
+// STM32F411RE Nucleo starter — Embassy async blink + UART echo.
+// LED pin: PA5 (Nucleo-F401RE/F411RE). Swap to PD12 for F4-Discovery, PC13 for Black Pill.
+// UART: USART2 on PA2(TX)/PA3(RX) — the Nucleo USB VCP bridge.
+
+#![no_std]
+#![no_main]
+
+use defmt::info;
+use embassy_executor::Spawner;
+use embassy_stm32::bind_interrupts;
+use embassy_stm32::gpio::{Level, Output, Speed};
+use embassy_stm32::peripherals::{DMA1_CH5, DMA1_CH6, USART2};
+use embassy_stm32::usart::{self, Config as UartConfig, Uart};
+use embassy_time::{Duration, Timer};
+use {defmt_rtt as _, panic_probe as _};
+
+bind_interrupts!(struct Irqs {
+    USART2 => usart::InterruptHandler<USART2>;
+});
+
+#[embassy_executor::task]
+async fn uart_echo_task(mut uart: Uart<'static, USART2, DMA1_CH6, DMA1_CH5>) {
+    info!("uart echo ready on USART2/PA2-PA3 @ 115200");
+    let mut buf = [0u8; 1];
+    loop {
+        if uart.read(&mut buf).await.is_ok() {
+            uart.write(&buf).await.ok();
+        }
+    }
+}
+
+#[embassy_executor::main]
+async fn main(spawner: Spawner) {
+    let p = embassy_stm32::init(Default::default());
+    info!("stm32-rust starter booting");
+
+    let uart = Uart::new(
+        p.USART2,
+        p.PA3,
+        p.PA2,
+        Irqs,
+        p.DMA1_CH6,
+        p.DMA1_CH5,
+        UartConfig::default(),
+    )
+    .unwrap();
+    spawner.spawn(uart_echo_task(uart)).unwrap();
+
+    let mut led = Output::new(p.PA5, Level::High, Speed::Low);
+    loop {
+        led.toggle();
+        Timer::after(Duration::from_millis(500)).await;
+    }
+}

package/registry/layers/framework/stm32-rust/manifest.json

@@ -0,0 +1,66 @@
+{
+  "id": "stm32-rust",
+  "description": "STM32 bare-metal Rust firmware using the Embassy async framework — #[embassy_executor::main], async GPIO blink on PA5, and a DMA-backed async UART echo on USART2/PA2-PA3. Targets STM32F411RE (Nucleo/Black Pill); swap HAL feature + memory.x for other chips. Flash + RTT via probe-rs.",
+  "appliesTo": ["stm32-rust"],
+  "files": [
+    { "source": "files/rust-toolchain.toml", "target": "rust-toolchain.toml" },
+    { "source": "files/src/main.rs", "target": "src/main.rs" },
+    { "source": "files/Embed.toml", "target": "Embed.toml" }
+  ],
+  "buildHints": {
+    "whenToUse": "Pick for STM32F/L/G series firmware in Rust when you want async/await (Embassy). For synchronous cortex-m-rt + RTIC, pick a different starter. For Raspberry Pi Pico, use rp2040-embassy.",
+    "firstSteps": [
+      "Install the Cortex-M4F target: rustup target add thumbv7em-none-eabihf",
+      "Install the flasher: cargo install probe-rs --features cli --locked",
+      "Connect an ST-Link (or any CMSIS-DAP probe) to the board",
+      "Build: cargo build --release",
+      "Flash + RTT: cargo run --release   (runs `probe-rs run --chip STM32F411RETx` via the cargo runner)",
+      "Open a serial terminal at 115200 baud on the Nucleo's USB COM port — anything you type echoes back"
+    ],
+    "gotchas": [
+      "memory.x must match the actual chip. STM32F411RE = 512K flash + 128K RAM; STM32F401RE = 512K flash + 96K RAM; STM32F103C8 = 64K flash + 20K RAM. Wrong values silently let the linker succeed then crash at boot.",
+      "embassy-stm32 requires exactly one chip feature — e.g. `stm32f411re`. Enabling two (or none) is a compile error with a misleading `time_driver_tim5 not found` message.",
+      "The cortex-m-rt link args (`-Tlink.x`, `-Tdefmt.x`) must be in .cargo/config.toml rustflags. If you put them in build.rs alone they only apply when the `build.rs` crate links, not the downstream bin.",
+      "defmt-rtt requires a running probe-rs to drain the RTT buffer. Without a probe attached at runtime the firmware will spin waiting for the RTT reader after ~1KB of logs.",
+      "Changing memory.x requires `cargo clean` — cargo does not see memory.x as a build input so the linker will use a stale copy from target/.",
+      "UART echo uses DMA1_CH6 (TX, stream 6) and DMA1_CH5 (RX, stream 5) for USART2. On STM32F4, channel numbers in Embed.toml refer to DMA streams. Swapping to a different UART requires picking the matching DMA stream pair from the STM32F4 reference manual.",
+      "bind_interrupts! must name the exact peripheral interrupt (USART2) that matches the peripheral passed to Uart::new. Mismatches are link-time errors, not compile-time."
+    ],
+    "architectureNotes": [
+      "Two tasks: the main task owns the LED and blinks at 500 ms; uart_echo_task owns the UART peripheral and echoes bytes. Embassy's executor multiplexes them cooperatively — no RTOS tick required.",
+      "Owned peripherals passed into a spawned task satisfy 'static because the peripheral tokens are zero-sized move-only values created by embassy_stm32::init(). The executor stores the task future in static memory.",
+      "DMA-backed UART read/write avoids CPU-spin in the echo loop. The DMA transfer completes asynchronously; the task yields via .await until the hardware interrupt fires."
+    ],
+    "placeholders": [
+      {
+        "path": "src/main.rs",
+        "description": "LED pin is PA5 (Nucleo-F401RE/F411RE). Change to PD12 for STM32F4-Discovery or PC13 (active-low) for Black Pill."
+      },
+      {
+        "path": "src/main.rs",
+        "description": "UART is USART2 on PA2 (TX) / PA3 (RX) — the Nucleo VCP bridge. Change peripheral + pins + DMA channels for boards without a VCP or when using a different UART."
+      },
+      {
+        "path": "Embed.toml",
+        "description": "chip = STM32F411RETx. Swap to STM32F401RETx for Nucleo-F401RE, STM32F407VGTx for STM32F4-Discovery, STM32F411CEUx for Black Pill."
+      }
+    ]
+  },
+  "contextHints": {
+    "commands": [
+      "rustup target add thumbv7em-none-eabihf",
+      "cargo build --release",
+      "cargo run --release",
+      "cargo check"
+    ],
+    "entrypoints": [
+      "src/main.rs",
+      "Cargo.toml",
+      "memory.x",
+      ".cargo/config.toml"
+    ],
+    "extensionPoints": [
+      "src/main.rs"
+    ]
+  }
+}

package/registry/layers/framework/streamlit-advanced/files/.env.example

@@ -0,0 +1,3 @@
+APP_SERVICE_NAME=starter-foundry-streamlit
+APP_HEADLINE=Streamlit Production Dashboard
+APP_SUBHEADLINE=Multipage Streamlit app with caching, Plotly, and typed settings.

package/registry/layers/framework/streamlit-advanced/files/README.md

@@ -0,0 +1,58 @@
+# Streamlit Production Dashboard
+
+Multipage Streamlit app with sidebar navigation, `st.cache_data`, Plotly charts, and typed env-driven settings via pydantic-settings.
+
+## Quick start
+
+```bash
+pip install -r requirements.txt
+cp .env.example .env   # fill in values
+streamlit run app.py
+```
+
+Opens on [http://localhost:8501](http://localhost:8501).
+
+## Project layout
+
+```
+app.py                  # entrypoint — sidebar, tabs, Settings class
+pages/
+  1_analysis.py         # analysis page (auto-registered by numeric prefix)
+.streamlit/
+  config.toml           # server port, theme
+requirements.txt        # Python deps
+.env.example            # documented env vars
+```
+
+## Configuration
+
+All settings are read from `APP_*` environment variables. See `.env.example` for the full list.
+
+| Variable            | Description         |
+|---------------------|---------------------|
+| `APP_SERVICE_NAME`  | Internal service label shown in sidebar |
+| `APP_HEADLINE`      | Page title and sidebar heading |
+| `APP_SUBHEADLINE`   | Sidebar caption beneath the heading |
+
+## Adding pages
+
+Drop a file into `pages/` using the `<number>_<Title>.py` naming convention:
+
+```python
+import streamlit as st
+st.set_page_config(page_title="My Page", layout="wide")  # must be first call
+st.title("My Page")
+```
+
+Streamlit auto-registers it in the sidebar in numeric order.
+
+## Caching
+
+- `@st.cache_data(ttl=...)` — DataFrames, API responses, computed values
+- `@st.cache_resource` — database connections, ML models (singleton per process)
+
+## Validation
+
+```bash
+node validate-streamlit.mjs
+```

package/registry/layers/framework/streamlit-advanced/files/analysis.py

@@ -0,0 +1,40 @@
+import pandas as pd
+import plotly.express as px
+import streamlit as st
+
+st.set_page_config(page_title="Analysis", page_icon=":microscope:", layout="wide")
+
+
+@st.cache_data(ttl=600)
+def load_sample() -> pd.DataFrame:
+    return pd.DataFrame(
+        {
+            "segment": ["A", "B", "C", "D", "E"],
+            "users": [1200, 950, 780, 640, 410],
+            "revenue": [48_000, 31_500, 22_100, 18_900, 9_400],
+        }
+    )
+
+
+st.title("Analysis")
+st.caption("Secondary page registered via the `pages/` convention.")
+
+df = load_sample()
+
+picked = st.multiselect(
+    "Segments",
+    options=df["segment"].tolist(),
+    default=df["segment"].tolist(),
+)
+view = df[df["segment"].isin(picked)]
+
+left, right = st.columns(2)
+with left:
+    st.subheader("Users by segment")
+    st.plotly_chart(px.bar(view, x="segment", y="users"), use_container_width=True)
+with right:
+    st.subheader("Revenue by segment")
+    st.plotly_chart(px.bar(view, x="segment", y="revenue"), use_container_width=True)
+
+st.divider()
+st.dataframe(view, use_container_width=True)