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

# Backend Service: shifu

This file adds local guidance for `src/api/flaskr/service/shifu`. 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 core shifu authoring, outline structure, draft history,
  publish, import/export, permissions, and resource-link management.

- Primary checked-in entry files today:
  `src/api/flaskr/service/shifu/route.py`,
  `src/api/flaskr/service/shifu/funcs.py`,
  `src/api/flaskr/service/shifu/models.py`,
  `src/api/flaskr/service/shifu/permissions.py`,
  `src/api/flaskr/service/shifu/shifu_history_manager.py`

- 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/shifu/` already exists and
  should remain the first stop.

## Do

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

- Preserve the separation between draft state, publish state, and history logs
  so authoring recovery remains trustworthy.

- Keep outline and structural mutations going through the dedicated shifu
  helper modules instead of ad-hoc tree edits.

- Treat import/export, ask-provider config, and permissions as cross-cutting
  contracts that need coordinated updates.

## Avoid

- Do not mutate outline structures directly from route handlers when the shifu
  helper modules already own those transitions.

- Do not change publish or import/export payload shapes without updating
  related history and validation behavior together.

- Do not bypass permission checks when adding authoring or admin operations in
  this module.

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

## Commands

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

- `cd src/api && pytest tests/service/shifu/ -q` for the narrowest focused
  regression pass while iterating on this module.

- `cd src/api && FLASK_APP=app.py flask db migrate -m "message"` and review
  the generated revision if schema or indexed business-key changes are made.

- `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/shifu/` 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/skills/shifu-authoring-flow/SKILL.md

- `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.
