content-factory/docs/demo-stack-guide.md

Demo Stack Guide (Task 019)

This guide runs a deterministic end-to-end demo from article brief to PUBLISH_COMMIT_CREATED with no external credentials.

1. Setup

From repository root:

docker compose up --build

The backend runs in demo mode in Compose:

• PIPELINE_DEMO_MODE=1
• local Git target: /demo/pipeline-demo-site.git
• fake deterministic section runtime with one fail-then-retry branch
• local infra only (Postgres/Redis/MinIO)

No real Codex, search, WHOIS, cloud S3, or GitHub credentials are required.

2. Role Selection

The app uses demo users via backend header selection:

• Editor flow (default): editor@example.com
• Admin actions: admin@example.com

For the article detail page, role hint query is available:

• Editor: /articles/<articleId>?role=editor
• Admin: /articles/<articleId>?role=admin

3. Happy Path

1. Open frontend: http://localhost:3000.
2. Create article from dashboard (New article).
3. Complete boundary questions and submit.
4. Generate plan and approve.
5. Start research and open evidence matrix.
6. Start draft production.
7. Open article detail:
   • one section job is expected to fail (deterministic demo failure),
   • retry it from Admin view.
8. Assemble draft.
9. Run SEO and language review, resolve suggestions.
10. Generate assets, upload files, approve assets.
11. Final approval with publishing settings.
12. Run publishing dry run.
13. Create publish commit.

Expected final status: PUBLISH_COMMIT_CREATED.

4. Failure Path (Visible)

Demo mode always creates one deterministic failed section scaffold attempt on draft start:

• SECTION_SCAFFOLD attempt 1 -> FAILED
• retry from /api/agent-jobs/{job_id}/retry -> auto-completes SUCCEEDED

This exposes failure/retry timeline behavior and retry policy UI controls.

5. Artifact Inspection

Workflow timeline and job logs

• Open article detail page.
• Verify mixed timeline entries for user/system/agent events.
• Admin sees detailed redacted stdout/stderr.
• Editor sees safe failure summary only.

Object storage (research artifacts/manifests)

In local integration-style runs with OBJECT_STORAGE_LOCAL_ROOT, artifacts are under:

• research/<article_id>/<run_id>/source-*/section.json
• research/<article_id>/<run_id>/source-*/metadata.json

In Compose (MinIO), inspect bucket ${OBJECT_STORAGE_BUCKET:-pipeline-local}.

Final Git commit payload

The publish commit manifest contains:

• content.path (markdown/mdx),
• frontmatter,
• assets[*].target_path.

Inspect repo in Compose:

docker compose exec backend git --git-dir /demo/pipeline-demo-site.git log --oneline -n 5
docker compose exec backend git --git-dir /demo/pipeline-demo-site.git show <commit_sha>:<content_path>

For local integration tests, repository path comes from PIPELINE_DEMO_PUBLISH_REPO_PATH (the smoke test sets a temp path).