Multi-project

Why projects

A project is the tenancy boundary in z4j. Agents, tasks, events, schedules, memberships - all scoped to a project.

Use one project per:

• Environment (staging, production).
• Business unit (marketing-queue, billing-queue).
• Customer (if you're running z4j for your customers).

Creating a project

• First project is created automatically at first-boot setup.
• Subsequent projects: API POST /api/v1/projects (requires org-level admin).

curl -X POST https://z4j.example.com/api/v1/projects \
  -H "Authorization: Bearer $SESSION" \
  -H "Content-Type: application/json" \
  -d '{"name": "billing-prod"}'

Agent → project binding

When you mint an agent token, you pick the project. The token is bound - an agent authenticated with token_A can only write to project_A.

Membership model

A user can belong to many projects with different roles per project:

User	project: staging	project: billing-prod
alice	admin	admin
bob	operator	viewer
charlie	viewer	none

See RBAC.

Project switcher

The dashboard's top-bar shows the active project. Switching reloads the tasks/events views with the new scope.

Audit log

Audit rows carry project_id. Export is per-project (?project_id=... query).

Archiving a project

DELETE /api/v1/projects/{slug} is a soft archive, not a hard delete. It requires a system administrator, CSRF protection, and a fresh MFA check. The brain refuses to archive the last active project.

Archiving sets is_active=false and hides the project from ordinary list views. Agents, tasks, events, schedules, memberships, and audit rows remain in the database. There is no public hard-delete or typed-confirmation workflow.

Cross-project queries

Not supported in v1. Each project is isolated. If you need cross-project metrics, export audit and events via API and aggregate externally.