API + BT Demo Consolidation

.gitignore

@@ -141,3 +141,4 @@ mydb.json
 /package-lock.json
 /ontology/*.properties
 catalog-*.xml
+/wip_notes/

AGENTS.md

@@ -564,13 +564,19 @@ behavior across backends (in-memory / tinydb) where reasonable.
 - **Vocabulary Examples**: `vultron/scripts/vocab_examples.py` - Canonical
   ActivityStreams activity examples; use as reference for message semantics
   and as test fixtures for pattern matching
-- **Demo Scripts**: `vultron/scripts/receive_report_demo.py`,
+- **Demo CLI**: `vultron/demo/cli.py` - Unified `click`-based entry point
+  (`vultron-demo` command); sub-commands for each demo plus `all`
+- **Demo Utilities**: `vultron/demo/utils.py` - Shared `demo_step`,
+  `demo_check`, `DataLayerClient`, and HTTP helper utilities used by all
+  demo scripts
+- **Demo Scripts**: `vultron/demo/receive_report_demo.py`,
   `initialize_case_demo.py`, `invite_actor_demo.py`,
   `establish_embargo_demo.py`, `status_updates_demo.py`,
   `suggest_actor_demo.py`, `transfer_ownership_demo.py`,
   `acknowledge_demo.py`, `manage_case_demo.py`,
-  `initialize_participant_demo.py` - End-to-end workflow demonstrations;
-  also used by `test/scripts/` and Docker Compose configs
+  `initialize_participant_demo.py`, `manage_embargo_demo.py`,
+  `manage_participants_demo.py` - End-to-end workflow demonstrations;
+  also used by `test/demo/` and Docker Compose configs
 - **Case States**: `vultron/case_states/` - RM/EM/CS state machine enums and
   patterns; use as reference for valid state transitions and preconditions
   - **State machine enums are authoritative**: When documentation and code
@@ -1136,10 +1142,19 @@ cd /tmp && markdownlint-cli2 \
 The `strict.markdownlint-cli2.yaml` file at the repo root contains the same
 rules as the default config with the `ignores` block removed.
 
+### Docs links must be relative
+
+Markdown links in `docs/` MUST be relative to the current file and MUST NOT
+go above the `docs/` directory (the site root). Keep relative paths as short
+as possible. For example, a link from `docs/a/b/c/file.md` to
+`docs/a/d/other.md` should be `../../d/other.md`.
+Use `mkdocs build --site-dir PATH` and `linkchecker PATH` to verify links
+before committing.
+
 ### Demo script lifecycle logging
 
 Demo scripts use `demo_step` and `demo_check` context managers (defined
-locally in each demo file) to log structured lifecycle events:
+in `vultron/demo/utils.py`) to log structured lifecycle events:
 
 - `demo_step(description)` — workflow step: logs 🚥 on entry, 🟢 on success,
   🔴 on exception (re-raises).
@@ -1148,7 +1163,7 @@ locally in each demo file) to log structured lifecycle events:
 
 Wrap every numbered workflow step and every verification block in these
 managers. See `notes/codebase-structure.md` "Demo Script Lifecycle Logging"
-for the durable pattern and `test/scripts/test_demo_context_managers.py`.
+for the durable pattern and `test/demo/test_demo_context_managers.py`.
 
 ### Archiving IMPLEMENTATION_PLAN.md
 

Makefile

@@ -94,4 +94,8 @@ api_dev:  ## Start API server in development mode
 
 .PHONY: docker_api_dev
 docker_api_dev: docker_up  ## Start API server in Docker in development mode
-	cd docker && docker-compose up api-dev
+	cd docker && docker-compose up api-dev
+
+.PHONY: integration-test
+integration-test:  ## Run demo integration tests (requires Docker)
+	./integration_tests/demo/run_demo_integration_test.sh

docker/Dockerfile

@@ -39,51 +39,8 @@ FROM dependencies AS api-dev
 ENV LOG_LEVEL=DEBUG
 CMD ["uv","run","uvicorn","vultron.api.main:app","--host","0.0.0.0","--port","7999","--reload"]
 
-FROM dependencies AS receive-report-demo
+FROM dependencies AS demo
 ENV PYTHONPATH=/app
-# The BASE_URL in the script will be overridden via environment variable
-CMD ["uv", "run", "python", "-m", "vultron.scripts.receive_report_demo"]
-
-FROM dependencies AS initialize-case-demo
-ENV PYTHONPATH=/app
-CMD ["uv", "run", "python", "-m", "vultron.scripts.initialize_case_demo"]
-
-FROM dependencies AS establish-embargo-demo
-ENV PYTHONPATH=/app
-CMD ["uv", "run", "python", "-m", "vultron.scripts.establish_embargo_demo"]
-
-FROM dependencies AS invite-actor-demo
-ENV PYTHONPATH=/app
-CMD ["uv", "run", "python", "-m", "vultron.scripts.invite_actor_demo"]
-
-FROM dependencies AS status-updates-demo
-ENV PYTHONPATH=/app
-CMD ["uv", "run", "python", "-m", "vultron.scripts.status_updates_demo"]
-
-FROM dependencies AS suggest-actor-demo
-ENV PYTHONPATH=/app
-CMD ["uv", "run", "python", "-m", "vultron.scripts.suggest_actor_demo"]
-
-FROM dependencies AS transfer-ownership-demo
-ENV PYTHONPATH=/app
-CMD ["uv", "run", "python", "-m", "vultron.scripts.transfer_ownership_demo"]
-
-FROM dependencies AS acknowledge-demo
-ENV PYTHONPATH=/app
-CMD ["uv", "run", "python", "-m", "vultron.scripts.acknowledge_demo"]
-
-FROM dependencies AS manage-case-demo
-ENV PYTHONPATH=/app
-CMD ["uv", "run", "python", "-m", "vultron.scripts.manage_case_demo"]
-
-FROM dependencies AS initialize-participant-demo
-ENV PYTHONPATH=/app
-CMD ["uv", "run", "python", "-m", "vultron.scripts.initialize_participant_demo"]
-
-FROM dependencies AS manage-embargo-demo
-ENV PYTHONPATH=/app
-CMD ["uv", "run", "python", "-m", "vultron.scripts.manage_embargo_demo"]
-
-FROM dependencies AS manage-participants-demo
-ENV PYTHONPATH=/app
-CMD ["uv", "run", "python", "-m", "vultron.scripts.manage_participants_demo"]
+COPY docker/demo-entrypoint.sh /app/demo-entrypoint.sh
+RUN chmod +x /app/demo-entrypoint.sh
+ENTRYPOINT ["/app/demo-entrypoint.sh"]

docker/demo-entrypoint.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+# Entrypoint for the unified Vultron demo container (DC-04-001, DC-04-002).
+#
+# When the DEMO environment variable is set, run that sub-command
+# non-interactively and exit.  Otherwise, display available demos and
+# drop into an interactive shell so the user can run `vultron-demo <name>`.
+
+set -e
+
+if [ -n "${DEMO}" ]; then
+    exec vultron-demo ${DEMO}
+fi
+
+# Interactive mode: show available commands then open a shell.
+echo ""
+echo "Vultron Demo Container"
+echo "======================"
+echo "Run a demo with:  vultron-demo <name>"
+echo ""
+vultron-demo --help
+echo ""
+exec bash

docker/docker-compose.yml

@@ -75,210 +75,12 @@ services:
       retries: 15
       start_period: 5s
 
-  receive-report-demo:
+  demo:
     build:
       context: ..
       dockerfile: docker/Dockerfile
-      target: receive-report-demo
-    image: ${PROJECT_NAME}-receive-report-demo:latest
-    depends_on:
-      api-dev:
-        condition: service_healthy
-    volumes:
-      - "../vultron:/app/vultron"
-      - "/app/.venv"
-    environment:
-      - PYTHONPATH=/app
-      - VULTRON_API_BASE_URL=http://api-dev:7999/api/v2
-    networks:
-      - vultron-network
-
-  initialize-case-demo:
-    build:
-      context: ..
-      dockerfile: docker/Dockerfile
-      target: initialize-case-demo
-    image: ${PROJECT_NAME}-initialize-case-demo:latest
-    depends_on:
-      api-dev:
-        condition: service_healthy
-    volumes:
-      - "../vultron:/app/vultron"
-      - "/app/.venv"
-    environment:
-      - PYTHONPATH=/app
-      - VULTRON_API_BASE_URL=http://api-dev:7999/api/v2
-    networks:
-      - vultron-network
-
-  establish-embargo-demo:
-    build:
-      context: ..
-      dockerfile: docker/Dockerfile
-      target: establish-embargo-demo
-    image: ${PROJECT_NAME}-establish-embargo-demo:latest
-    depends_on:
-      api-dev:
-        condition: service_healthy
-    volumes:
-      - "../vultron:/app/vultron"
-      - "/app/.venv"
-    environment:
-      - PYTHONPATH=/app
-      - VULTRON_API_BASE_URL=http://api-dev:7999/api/v2
-    networks:
-      - vultron-network
-
-  invite-actor-demo:
-    build:
-      context: ..
-      dockerfile: docker/Dockerfile
-      target: invite-actor-demo
-    image: ${PROJECT_NAME}-invite-actor-demo:latest
-    depends_on:
-      api-dev:
-        condition: service_healthy
-    volumes:
-      - "../vultron:/app/vultron"
-      - "/app/.venv"
-    environment:
-      - PYTHONPATH=/app
-      - VULTRON_API_BASE_URL=http://api-dev:7999/api/v2
-    networks:
-      - vultron-network
-
-  status-updates-demo:
-    build:
-      context: ..
-      dockerfile: docker/Dockerfile
-      target: status-updates-demo
-    image: ${PROJECT_NAME}-status-updates-demo:latest
-    depends_on:
-      api-dev:
-        condition: service_healthy
-    volumes:
-      - "../vultron:/app/vultron"
-      - "/app/.venv"
-    environment:
-      - PYTHONPATH=/app
-      - VULTRON_API_BASE_URL=http://api-dev:7999/api/v2
-    networks:
-      - vultron-network
-
-  suggest-actor-demo:
-    build:
-      context: ..
-      dockerfile: docker/Dockerfile
-      target: suggest-actor-demo
-    image: ${PROJECT_NAME}-suggest-actor-demo:latest
-    depends_on:
-      api-dev:
-        condition: service_healthy
-    volumes:
-      - "../vultron:/app/vultron"
-      - "/app/.venv"
-    environment:
-      - PYTHONPATH=/app
-      - VULTRON_API_BASE_URL=http://api-dev:7999/api/v2
-    networks:
-      - vultron-network
-
-  transfer-ownership-demo:
-    build:
-      context: ..
-      dockerfile: docker/Dockerfile
-      target: transfer-ownership-demo
-    image: ${PROJECT_NAME}-transfer-ownership-demo:latest
-    depends_on:
-      api-dev:
-        condition: service_healthy
-    volumes:
-      - "../vultron:/app/vultron"
-      - "/app/.venv"
-    environment:
-      - PYTHONPATH=/app
-      - VULTRON_API_BASE_URL=http://api-dev:7999/api/v2
-    networks:
-      - vultron-network
-
-  acknowledge-demo:
-    build:
-      context: ..
-      dockerfile: docker/Dockerfile
-      target: acknowledge-demo
-    image: ${PROJECT_NAME}-acknowledge-demo:latest
-    depends_on:
-      api-dev:
-        condition: service_healthy
-    volumes:
-      - "../vultron:/app/vultron"
-      - "/app/.venv"
-    environment:
-      - PYTHONPATH=/app
-      - VULTRON_API_BASE_URL=http://api-dev:7999/api/v2
-    networks:
-      - vultron-network
-
-  manage-case-demo:
-    build:
-      context: ..
-      dockerfile: docker/Dockerfile
-      target: manage-case-demo
-    image: ${PROJECT_NAME}-manage-case-demo:latest
-    depends_on:
-      api-dev:
-        condition: service_healthy
-    volumes:
-      - "../vultron:/app/vultron"
-      - "/app/.venv"
-    environment:
-      - PYTHONPATH=/app
-      - VULTRON_API_BASE_URL=http://api-dev:7999/api/v2
-    networks:
-      - vultron-network
-
-  initialize-participant-demo:
-    build:
-      context: ..
-      dockerfile: docker/Dockerfile
-      target: initialize-participant-demo
-    image: ${PROJECT_NAME}-initialize-participant-demo:latest
-    depends_on:
-      api-dev:
-        condition: service_healthy
-    volumes:
-      - "../vultron:/app/vultron"
-      - "/app/.venv"
-    environment:
-      - PYTHONPATH=/app
-      - VULTRON_API_BASE_URL=http://api-dev:7999/api/v2
-    networks:
-      - vultron-network
-
-  manage-embargo-demo:
-    build:
-      context: ..
-      dockerfile: docker/Dockerfile
-      target: manage-embargo-demo
-    image: ${PROJECT_NAME}-manage-embargo-demo:latest
-    depends_on:
-      api-dev:
-        condition: service_healthy
-    volumes:
-      - "../vultron:/app/vultron"
-      - "/app/.venv"
-    environment:
-      - PYTHONPATH=/app
-      - VULTRON_API_BASE_URL=http://api-dev:7999/api/v2
-    networks:
-      - vultron-network
-
-  manage-participants-demo:
-    build:
-      context: ..
-      dockerfile: docker/Dockerfile
-      target: manage-participants-demo
-    image: ${PROJECT_NAME}-manage-participants-demo:latest
+      target: demo
+    image: ${PROJECT_NAME}-demo:latest
     depends_on:
       api-dev:
         condition: service_healthy
@@ -290,6 +92,8 @@ services:
       - VULTRON_API_BASE_URL=http://api-dev:7999/api/v2
     networks:
       - vultron-network
+    stdin_open: true
+    tty: true
 
 networks:
   vultron-network:

docs/howto/activitypub/activities/acknowledge.md

@@ -65,3 +65,19 @@ flowchart LR
     about a message or object, such as `as:Like`, `as:Dislike`, and `as:Flag`.
     While these may be relevant to implementations of the Vultron protocol, we
     do not have specific use cases for them at this time.
+
+## Demo
+
+!!! example "Try it: `vultron-demo acknowledge`"
+
+    Run this workflow end-to-end with the unified demo CLI:
+
+    ```bash
+    vultron-demo acknowledge
+    ```
+
+    Or with Docker Compose:
+
+    ```bash
+    DEMO=acknowledge docker compose -f docker/docker-compose.yml run --rm demo
+    ```