# Agent Retrieval Contract

## 0. Canonical machine entry

The stable public machine/configuration landing page is:

https://inquirystack.philohub.workers.dev/agent/

An AI agent may be handed only that URL. It must then retrieve the canonical ecosystem and this contract, reconstruct all four components, and continue according to the rules below. The public landing page is a discovery surface; the GitHub-tracked ecosystem and contracts remain authoritative.

This document is the canonical cross-repository retrieval contract for the Inquiry Publishing Stack.

It does not merge AHICP, PPF, Vault Interface, or the Starter into one normative system. It defines how an AI agent reconstructs their relationship before configuring, upgrading, publishing, or operating a project.

## 1. Entry from any public surface

An agent may enter through any of these surfaces:

- an AHICP, PPF, Vault Interface, or Starter public homepage;
- any of the four GitHub repositories;
- a README, `AGENTS.md`, `ecosystem.yaml`, or `llms.txt`;
- a downstream project that declares adoption of one or more stack components.

From any such entrypoint, the agent must reconstruct the whole public ecosystem before making cross-component configuration decisions.

## 2. Mandatory retrieval sequence

1. Identify the current component.
2. Read that repository's `ecosystem.yaml` and ecosystem documentation.
3. Read this Starter contract and the canonical Starter `ecosystem.yaml`.
4. Resolve all four public components and their roles:
   - AHICP — human-led inquiry and creation governance;
   - PPF — source-centered publishing lifecycle and Continuous Web;
   - Vault Interface — provider-neutral public metadata contract;
   - Starter — composition, adoption, profile, and upgrade layer.
5. For a downstream project, read `project-stack.yaml`, its selected profile, the lock file, and—when present—`project-provisioning.yaml`.
6. For a **new project**, read the canonical Project Provisioning Contract. If the request relies on platform standing authorization, read the private platform-authorization state only after that control-plane access is authorized.
7. For every active AHICP or PPF component, fresh-read the pinned upstream manifest or template manifest before configuration or upgrade.
8. Retrieve other private project state only when the human has explicitly authorized that access.
9. Before any external-state write, distinguish proposal, authorization, execution, verification, and durable write-back.
10. Before any Cloudflare action, follow the shared Continuous Web and Cloudflare operational guide and the PPF provider-specific contract for the selected deployment profile.

Public-link traversal is a retrieval instruction. It is never authorization to access a private repository, private vault, provider account, credential, unpublished source, or deployment control plane.

## 3. Default new-project baseline

Unless the human explicitly selects a reduced profile, a newly configured project uses:

```text
full AHICP
+ full PPF
+ Vault Interface public metadata adapter
+ project-owned content
```

Reduced profiles remain available for legitimate cases, but selecting one is an explicit human deviation from the default baseline. An agent must not infer a reduced profile merely because a project appears simple.

For an ordinary new full-stack project, the preferred infrastructure profile is `workers-builds-native` with `private-project-quota-saver`: use the personal `ChongLiuPhil` GitHub account, keep the repository private, use `human-assisted-once-per-project` for the GitHub → Cloudflare connection, protect the Worker with `worker-scoped-access` by default, keep previews disabled until separately accepted, and require a second push to deploy automatically without renewed authorization. In the quota-saver profile, content-only changes do not start GitHub Actions, configuration pull requests targeting `main` use one lightweight contract job, `main` does not trigger a duplicate GitHub Web build, heavy GitHub workflows are manual, automatic success artifacts stay off, manual publication artifacts retain for one day, and Cloudflare Workers Builds owns the automatic production Web build. `agent-provisioned-external-ci` remains an optional advanced profile using `external-ci-required`; only that advanced profile requires reusable platform standing authorization, account-wide Access as a provisioning precondition, and the trusted Secret Broker. Public framework repositories use `full-validation` as their full-CI cost profile.

## 4. Default privacy and publication posture

For original, unpublished, research, manuscript, or other copyright-bearing project content:

- the canonical source repository is private by default;
- Continuous Web may still be prepared and deployed;
- unpublished or transitional Web output is restricted by default;
- reader authentication is implemented at the access layer, not by committing a password to Git;
- repository files store only a policy reference, never the secret credential;
- publication may later move from restricted to public after explicit human authorization;
- changing reader visibility does not imply changing the source repository from private to public.

A currently shared reading credential may be used as a transitional operational policy, but its secret value must remain provider-side and outside Git, logs, issues, pull requests, and chat.

## 5. Required agent reconstruction report

Before material configuration or upgrade work, the agent should be able to state:

- which component it entered through;
- the four component roles and public entrypoints;
- the selected downstream profile;
- active, deferred, and not-applicable components;
- pinned upstream revisions;
- source privacy and Web visibility;
- publication authorization state;
- Cloudflare deployment profile and access policy;
- project provisioning profile, CI cost profile, bootstrap mode, and `project-provisioning.yaml` state when applicable;
- for the default Native profile: repository owner/visibility, Workers Builds repository connection, actual Access mode, `private-project-quota-saver` behavior, first restricted deployment verification, and second-push no-reauthorization verification;
- only for the optional advanced External-CI profile: whether platform standing authorization covers the requested GitHub owner and Cloudflare scope, and whether the trusted Secret Broker plus isolated token-minting boundary are verified;
- which actions are already authorized and which remain human-reserved;
- which provider state still needs verification.

If those facts cannot be reconstructed, treat the situation as a configuration defect rather than guessing.

For private downstream projects, GitHub Actions is not an iterative debugging environment. Batch related edits, run available Agent-side preflight checks, inspect the complete diff, and trigger only the intended thin CI. If a run fails, inspect the complete failure set, batch the fixes, and prefer re-running only failed work. Do not create content-only Actions runs or enable paid Actions usage without explicit human authorization.

## 6. Public-delivery migration rule

For the four public framework sites, Cloudflare Workers is the preferred delivery provider and GitHub remains the canonical source/version-control provider.

The approved architecture composes the four repositories into **one website and one active Worker**. The user separately authorized `https://inquirystack.philohub.workers.dev/` as the canonical human entry and `/agent/` as the machine entry. Normative authorities remain independent. Read `docs/UNIFIED_PUBLIC_SITE.md` and the v3 migration plan. `site/sources.lock.json` pins website sources and does not replace downstream adoption locks.

The selected `workers.dev` address is free and requires no DNS change. The former framework GitHub Pages sites are retired; the approved Worker is the sole public website entry. Roll back through a previously verified Worker version or a reviewed revert. Read the actual migration and verification state from `templates/cloudflare-public-delivery.yaml`; do not infer a completed live cutover merely from authorization or CI. Protected previews remain disabled until their separate Access acceptance.

## 7. Cloudflare human-handoff standard

When a Cloudflare action cannot be completed through an already authorized tool, the agent must not say only “configure Cloudflare” or “enable Access.” It must give numbered, operator-level instructions that include:

1. where to sign in and which account/project/domain is the target;
2. the exact Dashboard area or current UI path to open;
3. the value or setting to choose, while clearly marking any value that must come from the project contract;
4. which secrets must not be copied into chat;
5. the completion condition the human should observe;
6. what the agent will verify after the human completes the step;
7. the rollback path if the operation changes routing, publication, or access.

If the live provider UI differs from a recorded runbook, the agent must inspect current provider documentation or UI rather than inventing a path.

## 8. Canonical public entrypoints

- AHICP: https://inquirystack.philohub.workers.dev/
- PPF: https://inquirystack.philohub.workers.dev/ppf/
- Vault Interface: https://inquirystack.philohub.workers.dev/vault-interface/
- Starter: https://inquirystack.philohub.workers.dev/starter/

Machine-readable ecosystem:
https://github.com/ChongLiuPhil/Inquiry-Publishing-Project-Starter/blob/main/ecosystem.yaml

Continuous Web and Cloudflare guide:
https://github.com/ChongLiuPhil/Inquiry-Publishing-Project-Starter/blob/main/docs/CONTINUOUS_WEB_CLOUDFLARE.md