storyden: Instructions file for Codex

AGENTS.md

Purpose

This file is the generic entrypoint for finding project documentation relevant to the current task. Use this as an index, then open only the docs needed for the work at hand.

Quick Orientation

• Product and scope:
  • README.md for product overview and goals.
  • web/ is the product application.
  • home/ is the website/docs app (only use when task targets docs/marketing site).
• Backend high-level direction (Go):
  • cmd/backend/main.go is the backend runtime entrypoint.
  • app/resources/**, app/services/**, app/transports/** are the core 3 layers (data, business logic, external interfaces).
  • internal/** contains infrastructure and platform integration code.
  • api/openapi.yaml and api/rpc/** are contract/spec roots for generated transport code.
  • internal/ent/schema/** is the DB schema source of truth.
• Local setup and workflow:
  • Taskfile.yml for canonical project task commands.
• Architecture and backend:
  • CLAUDE.md for high-level architecture map, layering rules, and command guardrails.
  • docs/architecture/ for deeper architecture notes when needed.
  • internal/config/config.yaml for runtime configuration surface.
• Frontend and design system (web):
  • Read web/AGENTS.md before editing frontend code. Its Storybook and component-reuse rules are the required frontend entrypoint.
  • web/panda.config.ts for Panda setup, tokens, recipes, patterns, and conditions.
  • web/src/theme/ and web/src/app/global.css for semantic tokens and global styling rules.
  • web/src/app/(dashboard)/**/README.md for route/domain intent.
• API and SDK:
  • api/openapi.yaml as API contract source of truth.
  • api/rpc/README.md and sdk/**/README.md for transport/SDK usage.

Backend Task Routing (Go)

Storyden backend is a Go application using Uber Fx dependency injection and a 3-layer app structure.

• Runtime composition and startup:
  • cmd/backend/main.go wires config, infrastructure, resources, services, and transports.
  • app/resources/resources.go, app/services/services.go, and app/transports/transports.go define dependency module composition.
• Layer responsibilities:
  • app/resources/**: persistence/data access and query/write repositories.
  • app/services/**: business logic and orchestration.
  • app/transports/**: external interfaces (HTTP OpenAPI, RPC, MCP).
  • internal/**: infrastructure and platform concerns (db, cache, mail, pubsub, vector, config, etc.).
• If your task is API endpoint behavior:
  • Start in app/transports/http/bindings/** for handlers/bindings.
  • Check generated types/server in app/transports/http/openapi/**.
  • Update API contract in api/openapi.yaml (and related api/common/** schemas) when request/response surface changes.
• If your task is domain/business logic:
  • Implement changes in app/services/<domain>/**.
  • Use app/resources/<domain>/** for data access changes needed by that logic.
• If your task is database/schema/persistence:
  • Source of truth is internal/ent/schema/**.
  • Regenerated artifacts are under internal/ent/**.
• If your task is infra/config wiring:
  • internal/infrastructure/** for adapters and integrations.
  • internal/config/config.yaml for environment-backed runtime configuration.
• If your task is plugins/RPC:
  • RPC schemas: api/rpc/** and api/plugin.yaml.
  • Transport/runtime implementation: app/transports/rpc/**, app/services/plugin/**, app/resources/plugin/**.
• If your task is MCP tools:
  • app/transports/mcp/** and app/transports/mcp/tools/**.