AGENTS.md

Guidance for coding agents working on nk304, an enterprise AI reasoning and workspace platform.

Project Overview

nk304 is a pnpm monorepo with a Python API, Python worker, Next.js frontend, shared packages, generated contracts, and a LangGraph-style assistant runtime.

Repository map:

• apps/web-next: Next.js App Router frontend with React, Tailwind, Zustand, Socket.IO, and i18n.
• apps/api-py: FastAPI + SQLModel async API, assistant runtime, transport crypto, migrations, and service layers.
• apps/worker-py: ARQ worker for background jobs.
• packages/shared: shared constants, enums, types, and utilities.
• packages/contracts: generated OpenAPI and WebSocket contracts.
• packages/api-sdk: API client factory with auth, CSRF, request metadata, and retry behavior.
• packages/app-core: shared application controllers and normalizers.
• packages/locales: locale bundles and language normalization.

Setup Commands

bashpnpm install
pnpm run dev
pnpm run build
pnpm run lint
pnpm run typecheck
pnpm run test
pnpm run db:migrate
pnpm run contracts:export
pnpm run contracts:generate

Use ./deploy.sh --status to inspect orchestration state before assuming services are running. Do not publish fixed local ports in docs; refer to the resolved API and web ports from the runtime scripts.

Architecture Rules

• API base stays under /api/v2.
• Web API calls should go through apps/web-next/src/services/api.client.ts unless the task is explicitly about client infrastructure.
• Generated contract files under packages/contracts must be regenerated, not hand-edited.
• WebSocket event names stay aligned with packages/shared/src/constants/index.ts.
• Assistant runtime stays under apps/api-py/app/assistant_graph/**.
• If a normal user-facing capability changes, check whether the assistant needs read or prepared-mutation parity.

Frontend Rules

• Follow existing shared shells, panels, forms, tables, empty states, and Tailwind token usage.
• Add English locale entries first when user-visible copy changes.
• Do not introduce one-off colors or theme literals unless the task explicitly requires it.
• Preserve transport-protected surfaces; do not bypass protected payload handling with raw URLs or ad hoc payloads.

Backend Rules

• Keep models, schemas, routes, services, and workers aligned.
• Queue job names must match enqueue callsites and worker registration.
• Database changes need migrations.
• BYOK paths should remain provider-bound through existing core modules; do not add local production embedding runtimes.

Testing

Use focused checks first, then broaden:

bashpnpm --filter @nk304/web-next run lint
pnpm --filter @nk304/web-next run typecheck
cd apps/api-py && uv run ruff check .
cd apps/api-py && uv run pytest tests/<path>.py -q
pnpm run verify:web-next:migration

For contract-sensitive changes, run pnpm run contracts:export and pnpm run contracts:generate, then verify consumers.

Security And Privacy

• Never publish credentials, tokens, raw environment values, private hosts, or machine-specific paths.
• Keep protected transport, CSRF, request ids, and auth metadata intact.
• Cloud and edge changes require a plan/status command first and a smoke/status check after.
• If a secret appears in chat, logs, or files, tell the user to revoke and rotate it.

Commit And PR Rules

• Keep changes scoped to the feature surface.
• State whether contracts, migrations, locale bundles, assistant tools, or worker tasks changed.
• Report exact targeted tests and any broad checks that were skipped.