> ## Documentation Index
> Fetch the complete documentation index at: https://docs.app.useharmonia.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Development

> Use explicit test fixtures, local emulators, and verification suites without confusing them with provider evidence.

## Test boundaries

Unit tests inject explicit collaborators at function boundaries. Shipped runtime code has no provider-success fixture mode: Bedrock and official publisher calls either execute with real credentials or fail visibly. Official DynamoDB Local and a versioned MinIO S3 service exercise persistence locally; SQS handlers are tested through injected transport boundaries; they do not constitute provider or deployment evidence.

## Local persistence harness

`MINIO_BINARY=/absolute/path/minio DYNAMODB_LOCAL_JAR=/absolute/path/DynamoDBLocal.jar npm run test:integration` launches isolated DynamoDB and versioned S3 on loopback ports 18766 and 18767. It owns its processes and does not provision cloud resources. Test credentials apply only to these local endpoints.

`scripts/dev.sh` starts web and worker with real Cognito configuration; it supplies no login bypass. Fargate workers consume SQS through native long polling, with durable claims, visibility renewal and receipt-based acknowledgement.

## Test suites

```bash theme={null}
# Web: lint, types, unit tests (vitest)
npm run lint && npx tsc --noEmit && PYTHON_BIN=agent/.venv/bin/python npm test

# Worker: pytest
cd agent && ./.venv/bin/python -m pytest tests -q
```

Worker tests set non-secret dummy configuration via `agent/tests/conftest.py` and inject provider responses only inside individual tests.

## Useful local endpoints

| Endpoint                                   | Purpose                                                                       |
| ------------------------------------------ | ----------------------------------------------------------------------------- |
| `GET /api/proposals`                       | Proactive proposal inbox feed                                                 |
| `GET /api/content-items`                   | Calendar items                                                                |
| `GET /api/notifications`                   | Bell notifications                                                            |
| `POST /api/chat`                           | Chat surface (`{message, surface}`)                                           |
| `POST /api/chat/stream`                    | Durable Console stream (`{message, surface, attachmentIds}`), NDJSON response |
| `POST /api/chat/attachments/session`       | Create a validated resumable upload session                                   |
| `POST /api/chat/attachments/{id}/complete` | Verify bytes, quarantine, scan, and mark ready only on a clean verdict        |
| `GET /api/chat/runs/{id}/events?after=N`   | Replay persisted stream events after sequence `N`                             |
| `GET /api/internal/insights`               | Verified engagement and eligible context fed into Nimi/Ryan                   |

Internal routes require service authentication plus workspace and brand headers. Dashboard routes require a Cognito-backed server session and derive the workspace from server-side membership.

S3 uploads require bucket CORS for the deployed web origin and the signed upload method. The browser receives only a scoped expiring upload URL, never AWS credentials. Quarantine scanning and byte verification must complete before source extraction. Configure the real S3 bucket or explicit local test endpoint; internal cloud assets use S3.