# Run Demo

This is the short path for the self-hosted demo flow.

Detailed reference:

- `docs/public/githubrepo/02-quickstart.md`
- `docs/public/githubrepo/06-agent-instructions.md`
- `test-repo-template/docs/policy-explained.md`

## 1. Use The Test Repo Template

Start with:

```text
test-repo-template/
```

Copy it into a new empty GitHub repository, commit it as the human owner, and
install the GitHub App only on that repository.

Make sure the Gateway allowlist matches that repository:

```text
INTENT_GATEWAY_ALLOWED_REPOS=owner/repo
```

If `.env` still contains `OWNER/REPO`, the dashboard and demo stay in a
partial state and the story demo will fail with `repo_allowlist`. This value
belongs in `.env`, not in `data/agents.env`.

## 2. Know The Test Policy

Bundled self-hosted examples:

- allowed path:

```text
config/live-demo-pass.yaml
```

- blocked path:

```text
security/live-demo-blocked.yaml
```

Important:

```text
config/* allows direct files under config/
```

It does not allow nested paths like:

```text
config/demo/file.yaml
```

## 3. Prepare The Agent Inputs

The agent needs:

- `INTENT_GATEWAY_URL`
- `INTENT_GATEWAY_API_KEY`
- `GITHUB_READ_TOKEN`
- `TEST_REPO`
- `TEST_BRANCH`

The agent must have **no direct GitHub write access**.

The story demo is a functional test. It checks Gateway decisions by submitting
intents to the Gateway. It is not by itself proof that the agent environment is
isolated from every unrelated GitHub write credential on the machine.

If the shell is not already configured, the story demo first looks for:

```text
data/agents.env
```

Values already set in the shell still win. `TEST_REPO` is required and must
match `INTENT_GATEWAY_ALLOWED_REPOS` in `.env`. If you changed
`IGW_HOST_PORT`, the generated `INTENT_GATEWAY_URL` should use the same host
port.

## 4. Check The Test Repo

Before the Story Demo writes anything, check that the GitHub test repo was
created from the bundled template and contains the policy file:

```powershell
python examples/self-hosted/check-test-repo.py
```

This check reads GitHub with `GITHUB_READ_TOKEN`. It does not submit a Gateway
intent and does not create a branch, commit, or pull request.

## 5. Run The Story Demo

From the extracted self-hosted folder:

```powershell
python examples/self-hosted/github-gateway-story-demo.py
```

The demo prints the target repo and branch before it starts. If `TEST_REPO`
does not match the configured Gateway allowlist, it stops early with a local
error instead of sending a confusing blocked request.

## 6. What The Demo Should Show

The intended cases are:

- allowed write under `config/live-demo-pass.yaml`
- blocked write under `security/live-demo-blocked.yaml`
- stale state conflict after the repository state changes
- follow-up update on the same Gateway pull request

Content-sanity validation is a separate smoke check, not part of the default
story demo. Use an implemented format failure such as invalid YAML/JSON or
executable/binary content. Synthetic key-like text in valid YAML is not a secret
scanner test.

## 7. Expected Outcomes

- **Admitted**: a reviewable pull request is created
- **Blocked**: no repository impact
- **Conflict**: the agent must re-read and resubmit
- **Follow-up**: the same Gateway pull request is updated

Watch the dashboard activity feed while the demo runs. It should show sanitized
decision data, not raw payloads or secrets.

For the isolation proof, run the agent environment without ambient GitHub write
credentials. If you do not have a local clone of the test repository, skip the
push-isolation check and do not treat that as a story demo failure.
