← Back to registry

Artifact Runtime · SKILL

Canonical runtime-backed view of the artifact, independent from metadata governance.

Resolved Artifact

{
  "frontmatter": {
    "description": "Standardized procedure to deploy, clone, and configure routing for a new ImagineOS Loco.rs app.",
    "name": "create-loco-app"
  },
  "kind": "skill",
  "playbook": "# Skill: Bootstrapping a new ImagineOS Loco App\n\nThis skill provides the authoritative steps to clone an existing Loco.rs app, set up its database, inject the OS-v3 standard UI shell, and expose the app via the Sentinel and GCP Caddy ingress layers.\n\n## Execution Steps\n\n1. **Clone the App**: Use a script like `/tmp/clone_app.py` to copy a base app (e.g., Garcero, Cartera) to avoid copying `target/` and `.git/`. Ensure the python script does a deep search-and-replace for the old app name (e.g., `garcero` -> `newapp`).\n2. **Ports & Database**: \n   - **CRITICAL**: Check `/home/paulo/Programs/apps/OS/etc/sentinel/services.conf` to see what ports are already in use. Do not reuse an existing port or PM2 will crash-loop the app!\n   - Modify `config/development.yaml` and `config/production.yaml` with the new target `server.port` and `database.uri`.\n3. **Migrate DB**: Run `cargo loco db status` (and migrate if necessary).\n4. **Public Shell & CMS**: Replace `assets/content/pages/` with the new app's landing copy. Ensure `insert_public_shell_context` is actively used in `src/controllers/home.rs`.\n5. **Route Registration Rules**: When adding a controller:\n   - Export in `src/controllers/mod.rs` (`pub mod my_controller;`)\n   - Add the router in `src/app.rs`\n   - **CRITICAL**: Use `AppRoutes::empty().add_route(...)` instead of `AppRoutes::with_default_routes()`. Loco-rs defaults contain deprecated `/:` syntax that will immediately panic Axum 0.7 on startup.\n6. **Tera Template Resolution**: Shared OS-v3 `concat!` macros in `load_templates()` MUST point to `../OS-v3` as `CARGO_MANIFEST_DIR` resolves to the app's root (e.g., `/Apps/MyApp`), not the workspace root.\n7. **Agent Instantiation**: Do NOT hardcode prompts into Rust strings. ALWAYS read the persona from `OS/Agents/.md`.\n7. **Sentinel Routing (Local Edge)**: Map `.paulovila.org = ` in `OS/etc/sentinel/services.conf`.\n8. **GCP Caddy Routing (Public Edge)**: SSH into the GCP ingress and map `.paulovila.org { reverse_proxy 10.0.0.X:80 }` in `/etc/caddy/Caddyfile`, then reload the service to provision TLS.\n9. **PM2 Deployment**: Run `cargo build --release` and `pm2 start target/release/ --name  -- start`.\n\n## Important Limitations\n- Never forget step #8! Just adding it to Sentinel will result in `ERR_SSL_PROTOCOL_ERROR` because Cloudflare/GCP won't negotiate certificates for unknown mapped subdomains on the edge proxy.\n- **Content-Security-Policy (CSP) blocks**: Sentinel globally injects a strict CSP. If a new app requires custom external CDNs (like `uicdn.toast.com`), you MUST whitelist them in `Sentinel/src/main.rs` and re-deploy Sentinel, otherwise the browser will silently block them.\n- Always run `cargo check` after changing routers to catch trait mismatches.\n",
  "summary": {
    "description": "Standardized procedure to deploy, clone, and configure routing for a new ImagineOS Loco.rs app.",
    "id": "create-loco-app",
    "kind": "skill",
    "path": "Skills/create-loco-app/SKILL.md",
    "title": "create-loco-app"
  },
  "validation_issues": []
}

Validation