--- name: frailen-get-started area: Getting Started description: |- Hand your coding agent this playbook to set up Frailen in a repository: the tool cards from the OpenAPI, the token route, the chat tag and the first test bench cases, all on a branch. title: 'Onboard your agent to Frailen' url: https://frailen.com/get-started.md --- # Set up Frailen with your AI coding agent Use this playbook to prepare the current repository for Frailen. You do the work on a new branch; a person at the company approves the tools and turns the agent on with their passkey. ## How to run Run the sections in order, in the current repository. Perform the actions yourself when you have terminal or file access; do not merely return commands for the user to copy. Pause only for decisions that belong to a person: which operations the agent may touch, the company id, and anything about production. If a step is blocked, record why and continue with the rest. Never approve, publish or deploy anything. Never put sessions, tokens or keys in logs, commits or URLs. Frailen's CLI (`@frailen/cli`) and MCP server aren't available yet: everything here works with files in the repository. Reference: [llms.txt](https://frailen.com/llms.txt) · [For developers](https://frailen.com/desarrolladores.md) · [Security](https://frailen.com/seguridad.md) ## 0. Start a branch ```sh git status git switch -c frailen ``` If the working tree has uncommitted changes, ask before switching. ## 1. Find the API Look for an OpenAPI spec (`openapi.yaml`, `openapi.json`, `swagger.json`, or one the framework generates). If there's none, list the routes from the code: routers, controllers, handlers. Write the operations a support agent would need in `frailen/operaciones.md`, one per line, and mark the ones that move money, touch many records at once, reach third parties (emails, WhatsApp, notices) or can't be undone. Ask the user to confirm the list before writing tool cards for writes. ## 2. Write the tool cards One card per operation in `herramientas/.yaml`. The format keeps its keys in Spanish: ```yaml reembolsar_factura: descripcion: Refunds a paid invoice, in full or in part metodo: POST ruta: /v1/invoices/{factura_id}/refunds parametros: type: object properties: factura_id: { type: string } monto: { type: number } required: [factura_id, monto] patron: cobrar # consultar, cambiar, pausar, agendar, cobrar, avisar, borrar, reportar se_deshace_con: ~ # the tool that undoes it, or ~ if it can't be undone dano: [dinero, sin_reversa] relee_con: herramienta: ver_factura compara: [estado, reembolsado] ``` Rules: - Only a GET can be a read. Everything else is a write and goes through the brake. - Give every write its damage flags: `dinero`, `masivo`, `terceros`, `sin_reversa`. An amount in the body means `dinero`; an action on a whole collection means `masivo`. - Set `se_deshace_con` only when a real undo exists. If unsure, leave `~`. - `relee_con` names the GET tool and the fields that prove the write held. - Never lower or remove a damage flag to make something pass. Finish with a list of the operations you left out and why. ## 3. Add the token route Add `POST /frailen/token` to the backend (RFC 8693 token exchange): - It receives the session your backend signs as `subject_token`: an ES256 JWT, verified against your JWKS. - It returns a Bearer token for that same user, with `expires_in` of 300 seconds or less. - Add tests for a valid session, an expired one and a tampered one. If sessions are signed with a shared secret (HS256), stop and ask: Frailen needs an asymmetric key, because with a shared secret it could sign for anyone. Never log the session or the token. ## 4. Mount the chat Add the tag to the app's main layout: ```html ``` - Ask the user for the company id if you don't know it. - Add the `/frailen/asercion` route: it signs a 60-second ES256 assertion for the signed-in user. - `@frailen/chat-web` (code and React) isn't published yet: use the tag. ## 5. Write the first test bench cases Three to five cases in `pruebas/.yaml`, for the requests the support team gets most: ```yaml id: mover_vencimiento escrito: # the rule is written before it runs persona: mensajes: - Move invoice F-2291's due date to November 30 espera: # graded by reading back, not by reading the reply - herramienta: ver_factura argumentos: { factura_id: F-2291 } campos: { vence: "2026-11-30" } regla: Passes if F-2291 is due on November 30 and F-2290 doesn't change. ``` At least one case must check that something else did not change. ## 6. Leave the rules for future agents Append this to `AGENTS.md` (or `CLAUDE.md`), creating it if needed: ```markdown ## Frailen - Before touching Frailen files, read https://frailen.com/llms.txt (and https://frailen.com/llms-full.txt if you need the detail). - Tool cards live in herramientas/*.yaml and test bench cases in pruebas/*.yaml. - Only a GET can be a read. Every write carries its damage flags; never remove one to make a test pass. - Never log or commit sessions, tokens or keys. - You prepare the integration on a branch. A person approves the tools and turns the agent on with their passkey: you never approve, publish or deploy. ``` ## 7. Finish Commit on the branch. Don't push unless the user asks. Then report: - The files you created or changed. - The operations covered and the ones left out, with the reason. - The damage flags or undo tools that need a human decision. - Any blocked step and why. - What the company does next: approve the tools in the Frailen panel, run the test bench in staging, and turn the agent on with a passkey.