<!-- Generated by scripts/generate_ai_collab_docs.py. Edit metadata in that script. -->

# Backend Service: active

This file adds local guidance for `src/api/flaskr/service/active`. Read the
repository root and `src/api/AGENTS.md` first, then use this file for
module-specific ownership and risk points.

## Scope

- This service owns a reserved service namespace for activation-related
  behavior. The directory currently has no checked-in source files beyond
  caches..

- Primary checked-in entry files today: No checked-in source files are present
  yet.

- Keep behavior in this module unless the concern is clearly cross-service and
  shared by multiple backend domains.

- Preferred pytest location: `src/api/tests/service/active/` does not exist
  yet; create it when this service gains or changes behavior.

## Do

- Start from the local entry files and preserve how this service already
  structures helpers, models, routes, and DTO-like helpers.

- Introduce real source files before wiring imports or route registration into
  the application factory.

- Make ownership explicit in new files so future agents know whether
  activation, entitlement, or status logic belongs here.

- Add the first focused pytest suite at the same time the namespace starts
  owning runtime behavior.

## Avoid

- Do not rely on `__pycache__` artifacts as a source of truth for business
  behavior.

- Do not register placeholder modules or imports that point to files which are
  not committed.

- Do not spread activation logic across unrelated services once this namespace
  becomes active.

- Avoid scattering service-specific rules upward into root docs when the
  behavior only matters inside this module.

## Commands

- `rg -n "active" src/api/flaskr/service src/api/tests` to locate all backend
  call sites and tests before editing.

- `cd src/api && pytest -q` until `src/api/tests/service/active/` exists;
  create that directory first when this service gains behavior that needs
  focused regression coverage.

- `cd src/api && pytest -q` is usually enough unless work here also changes
  shared models in another service.

- `cd src/api && pytest -q` when a change touches shared DTOs, auth, streaming
  contracts, or other services in addition to this module.

## Tests

- Add or update focused tests around `src/api/tests/service/active/` for the
  happy path and the highest-risk validation, permission, or failure case.

- Expand coverage when payload shapes, error codes, or shared helper contracts
  used outside this module change.

- Review persistence-related changes manually for indexing, business-key
  semantics, and migration output whenever models move.

- Document any skipped provider, network, or credential-dependent checks in
  the final task summary.

## Related Skills

- `src/api/SKILL.md`

- `SKILL.md`

- Create a new backend skill under `src/api/skills/<topic>/SKILL.md` when this
  module grows a repeatable multi-step debugging workflow.
