dev3000 AGENTS.md

AGENTS.md

This file is the source of truth for agent guidance in this repo. CLAUDE.md is symlinked here.

Runtime

• Use d3k as the default local runtime.
• Canonical Portless HTTPS URLs are required by default and must be genuinely port-free (for example, https://my-app.localhost). Before starting d3k, run d3k portless status --json; if setup is required, run d3k portless setup, wait for the one-time administrator authorization, and verify Portless again. Do not start the app or browser until canonical Portless is ready unless the user explicitly requests --no-portless.
• When the user asks to use, test, debug, or develop with d3k, start it in a retained background tool session. Do not make the user launch it or switch to the TUI.
• Do not run bun run dev or bun run build for www/.
• Start d3k with:

  d3k -t
  

• Primary debugging commands:

  d3k status --json
  d3k errors --context
  d3k logs -n 200
  d3k logs --type browser
  d3k logs --type server
  

• Drive the monitored browser with:

  d3k agent-browser snapshot -i
  d3k agent-browser click @e2
  

  The session's CDP port is auto-connected. To target a different session, run d3k agent-browser connect <port> first.

Local UI, Production Workflows

• Local www/ is for the UI only.
• Workflow execution, workflow orchestration, and sandbox activity must run in production, not in the local Next server.
• On localhost, workflow API routes must proxy to production instead of starting workflows or managing sandboxes in-process.
• When testing locally, treat localhost as a production-backed shell:
  • start runs from the local UI
  • let production own workflow startup, execution, retries, and completion
  • let production own sandbox creation, sandbox control, and sandbox logs
  • let report pages and runs pages read workflow state from production APIs or shared remote storage
• Do not add new local-only workflow shortcuts, localhost-only workflow execution paths, or tmp-cache fallbacks unless the user explicitly asks for them.
• Do not make localhost the source of truth for workflow state.
• If local workflow storage is ever needed for debugging, gate it behind an explicit env var and keep it off by default.
• If a workflow feature behaves differently locally than in production, prefer removing the local special case rather than extending it.