Fix deploy env-template gaps and stale ai-agent docs from discussion #305

[pikann]

Summary

Follow-up to discussion #305 (first-install feedback from @HCH-hash): fixes the deploy/env-template gaps it identified, plus two doc and code issues found while investigating the ACP-agent credential question in that thread.

Docs: docs/ai-agent/overview.md, docs/ai-agent/api-design.md

Both predated the ACP agent feature entirely — they described a single LLM/Docker-sandboxed execution model, a since-removed "Agent Type" template concept, and REST paths/response shapes that no longer match the router (GET /api/v1/agent-types 404s; conversations moved from agent-scoped to project-scoped; several envelopes and query params had drifted). Rewrote both against the current router, DTOs, and service layer, including:

• The agent_type (llm/acp) split and where each executes
• The ACP credential model: agents authenticate via the user's own local CLI login through the paca-acp-bridge daemon — never an AGENT_API_KEY or llm_api_key
• The skill-templates replacement for the old built-in agent types

Deploy: deploy/.env.production.example, deploy/README.md

• PACA_*_IMAGE defaults were missing the pacaai/ registry prefix the compose file actually falls back to (bare paca-api:latest etc. don't resolve)
• Added INTERNAL_API_KEY, AGENT_API_KEY, SITE_ADDRESS, and PACA_AI_AGENT_IMAGE, none of which were in the template despite being referenced by docker-compose.prod.yml and the README's own manual-setup instructions
• Documented that INTERNAL_API_KEY is unconditionally required by the api service at startup — including with --scale ai-agent=0 — which the README previously implied was conditional on using the AI agent
• Surfaced PACA_YES=1, the install script's existing non-interactive/CI mode, which wasn't mentioned anywhere in deploy/README.md

API: pagination + encryption-key visibility

• task, conversation, project, and user list handlers silently substituted a default page_size for any out-of-range or non-numeric value instead of erroring. A caller driving pagination off the size it requested (e.g. computing the next offset as N * page_size) would get a smaller page back with no signal — skipping or duplicating rows against its own math. An absent page_size still defaults silently as before; an explicitly supplied invalid value now returns 400 via a new shared parsePageSize helper.
• Logs a warning when ENCRYPTION_KEY is unset. Previously fully silent: encryptKey() falls back to storing the plaintext unchanged, so LLM-type agent API keys and plugin secrets would end up in the database unencrypted with nothing in the logs to explain why. Left as a warning, not a hard failure — ACP-only deployments with no plugins storing secrets have no use for it.
• AGENT_API_KEY and INTERNAL_API_KEY were also investigated as fail-fast candidates: INTERNAL_API_KEY is already a hard requireEnv failure at startup, and AGENT_API_KEY is correctly optional by design, so neither needed a code change — just the env-template fix above.

Test plan

• go build ./... and go test ./... pass in services/api
• gofmt -l clean on touched Go files
• Manual: run install.sh with PACA_YES=1 end-to-end against the updated .env.production.example guidance

[pullfrog]

Important

Stale e2e pagination tests will break — see below.

Reviewed changes — clarifies ACP vs LLM agent credential requirements in self-host documentation and changes page_size query parameter handling from silent clamping to explicit rejection in four REST handlers, with a new parsePageSize helper.

• Document ACP / LLM agent type split in API design docs — rewrites docs/ai-agent/api-design.md and docs/ai-agent/overview.md to cover both agent types, adds new endpoints for ACP bridge token/status, agent env vars, skill templates, and LLM models. Rewrites conversations endpoint from agent-scoped to project-scoped cursor pagination.
• Add SITE_ADDRESS, INTERNAL_API_KEY, and AGENT_API_KEY to deploy environment — deploy/.env.production.example and deploy/README.md now document the TLS/domain control var, the unconditional internal key requirement, and the optional agent callback key. Also documents PACA_YES=1 for CI installs.
• Surface missing ENCRYPTION_KEY as a startup warning — app.go logs a Warn when ENCRYPTION_KEY is absent, replacing the previous silent fallback to plaintext storage.
• Reject invalid page_size instead of silently clamping — helpers.go gains parsePageSize; four handlers (conversation, task, user, project) switch from manual Atoi+clamp to parsePageSize with error propagation. Unit tests updated.

⚠️ Stale e2e pagination tests still assert silent page_size clamping

The e2e test suites for task and conversation pagination were not updated to match the new rejection behavior. They send page_size=0 and page_size=201 and assert a 200 response with the value clamped to 20 — but the handlers now return 400 Bad Request for both.

The unit-level conversation_handler_test.go was updated correctly, but the corresponding e2e tests were missed. These will fail on CI.

Technical details

# Stale e2e pagination tests still assert silent `page_size` clamping

## Affected sites
- `services/api/test/e2e/task_pagination_test.go:171` — `page_size_zero_is_clamped_to_default` asserts 200 with `page_size=20` when `page_size=0` is sent; the handler now returns 400.
- `services/api/test/e2e/task_pagination_test.go:178` — `page_size_over_max_is_clamped_to_default` asserts 200 with `page_size=20` when `page_size=201` is sent; same issue.
- `services/api/test/e2e/conversation_pagination_test.go:210` — `page_size_zero_is_clamped_to_default` same pattern for the conversations endpoint.
- `services/api/test/e2e/conversation_pagination_test.go:217` — `page_size_over_max_is_clamped_to_default` same pattern.

## Required outcome
- Update these four e2e test cases to expect HTTP 400 (Bad Request) and an error body, with a matching `{"error": "page_size must be an integer between 1 and 200"}` assertion, instead of asserting a successful clamped response.

  ^{｜ Fix it ➔ ｜ View workflow run ｜ Using DeepSeek Pro (free via Pullfrog for OSS) (Kimi K2 not used — the program covers this model; add its provider key to run your pick) ｜ 𝕏}

[pullfrog]

Reviewed changes — one commit addresses the prior review's e2e test concern and does a cosmetic parameter rename in parsePageSize.

• Updated e2e pagination tests to match the page_size rejection behavior — the four stale test cases that asserted silent clamping for page_size=0 and page_size=201 in conversation_pagination_test.go and task_pagination_test.go now assert HTTP 400 Bad Request, matching the handler logic introduced in 0ac3dbe.
• Renamed parsePageSize parameter max → maxSize for consistency with the defaultSize parameter name.

  ^{｜ View workflow run ｜ Using DeepSeek Pro (free via Pullfrog for OSS) (Kimi K2 not used — the program covers this model; add its provider key to run your pick) ｜ 𝕏}