AGENTS.md

Agent instructions

This repo is the TypeScript implementation of the Render Ops Agent workshop.

Product shape

• The facilitated path is TypeScript.
• main is the completed reference implementation.
• starter should be a separate branch with TODOs for the live workshop.
• A future Python repo can mirror this architecture, but do not mix Python into this repo.

Architecture

• ops-agent is a Hono web service that runs the agent.
• ops-target is a seeded target service for inspection.
• Postgres stores run history and finding memory.
• The TUI calls POST /run on AGENT_URL.
• Render API access must stay read-only. Keep the GET-only guard in agent/render-api.ts.

Local development

• .env is ignored and must never be committed.
• npm run dev loads .env if it exists.
• npm run tui loads .env if it exists.
• DATABASE_URL is optional locally. Without it, the agent runs without memory.
• If DATABASE_URL is set locally, run npm run db:migrate:local.

Render Blueprint

• Always validate render.yaml after changing it:

render blueprints validate

• The Blueprint should stay project-scoped under projects.
• Keep DATABASE_URL wired with fromDatabase.
• Keep migrations in preDeployCommand.

TUI guidance

• The TUI should stay useful but not become the workshop focus.
• Use @assistant-ui/react-ink-markdown for agent reply markdown rendering.
• Do not hand-roll a markdown parser.
• The TUI should show live run progress events, not private model reasoning.
• Keep user prompts visible in history.

Model output

• Agent replies should not use emoji.
• The prompt should encourage valid Markdown with blank lines between headings, paragraphs, and lists.
• Do not tell the model to expose chain-of-thought or private reasoning.

Git workflow

• Do not commit unless the user explicitly asks.
• When asked to commit, keep commits small and focused.
• Do not commit .env, credentials, or local build artifacts.