Session 27: Simplify USER-GUIDE.md to single instruction

[MarcoPolo483]

Reduced from 1,581 lines to 72 lines. USER-GUIDE.md now tells agents to call GET /model/agent-guide endpoint for complete guidance. API is single source of truth - no more doc drift.

[Copilot]

Pull request overview

Simplifies the agent-facing user guide by trimming USER-GUIDE.md down to a single instruction that points agents at the live GET /model/agent-guide endpoint, making the API the source of truth.

Changes:

• Replaced the ~1,500-line USER-GUIDE.md with a short pointer to GET /model/agent-guide.
• Expanded the API’s agent_guide() payload with a cloud URL and additional “common mistakes” entries.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File	Description
api/server.py	Adds cloud URL metadata and more “common mistakes” guidance to the agent_guide() API response.
USER-GUIDE.md	Collapses the guide into a single instruction to fetch the full guide from GET /model/agent-guide.

[Copilot]

The guide presents localhost as a supported “Local (development)” option. This conflicts with the PR’s stated goal (“Cloud … sole source of truth” and “no more doc drift”) and can mislead agents into using a non-authoritative or disabled endpoint. Consider removing the localhost example entirely, or clearly labeling it as “only when running the model API locally (not authoritative / may be disabled)” and emphasizing cloud/APIM as the default.

[Copilot]

agent_guide() now publishes both a localhost base_url and a cloud URL. Given the PR description that cloud is the sole source of truth (and local may be disabled), exposing base_url as a peer can cause clients/agents to pick the wrong endpoint. Consider either (a) renaming to local_url and marking it explicitly as non-authoritative/optional, or (b) omitting it from the guide payload if it should not be used.

Suggested change

	"Store=Cosmos in production. Store=memory in local dev."
	),
	"base_url": "http://localhost:8010",
	"Store=Cosmos in production (cloud_url is canonical). "
	"Store=memory in local dev (local_url is optional, non-authoritative)."
	),
	"local_url": "http://localhost:8010",

[Copilot]

“Backup guide is in your conversation history” isn’t a reliable or accessible fallback for many users (fresh sessions, different agents, CI, new contributors). Provide a concrete fallback that lives in-repo (e.g., a short “minimum viable workflow” section, or a link to a versioned snapshot/tag) so the documentation remains usable when the service is down.

Suggested change

	If the API is unreachable, the backup guide is in your conversation history. But **ALWAYS try the API first** - it has the latest guidance including lessons learned from recent sessions.
	If the API is unreachable, use this **minimum viable workflow** as an in-repo backup. When the API comes back, switch to `GET /model/agent-guide` for the full, up-to-date guidance.
	### 1. Assume Standard Base URLs
	- Cloud (production): `https://msub-eva-data-model.victoriousgrass-30debbd3.canadacentral.azurecontainerapps.io`
	- Local (development): `http://localhost:8010`
	Always prefer the cloud URL unless you have explicit instructions to use local.
	### 2. Bootstrap Call Sequence (Read-Only)
	When the service is available again, but before the guide endpoint itself is reachable, follow this sequence:
	1. `GET /health` – confirm the service is alive.
	2. `GET /model/ready` – confirm the model is ready for queries.
	3. `GET /model/agent-summary` – get high-level description of layers and endpoints.
	4. `GET /model/list` (or equivalent list endpoint) – list a small page of records with `?limit=20`.
	5. `GET /model/{layer}/{id}` – fetch a single record by id from a layer you discovered in step 3–4.
	Use `limit=20` and `offset=0` by default, and avoid fetching large unbounded result sets.
	### 3. Safe Query Defaults
	- Use `GET` only until you have explicit, in-guide confirmation of write rules.
	- Prefer small pages: `?limit=20&offset=0`.
	- If a filter parameter is available (e.g., `active_only=true`), prefer it to reduce result size.
	- When using PowerShell, add `| Select-Object -First 20` and `| ConvertTo-Json -Depth 10` to keep output readable.
	### 4. Writes Are Disabled in Emergency Mode
	- Do **not** perform any `PUT`, `POST`, `PATCH`, or `DELETE` operations while operating solely from this emergency section.
	- Wait for `GET /model/agent-guide` to be reachable so you can read the full write-cycle rules (row_version handling, audit stripping, required headers).
	### 5. Core Safety and Forbidden Actions (Summary)
	- Treat the HTTP API as the **only** supported interface; do not read raw `model/*.json` files or database tables directly.
	- Do not run repo-wide text search/grep to infer schema; rely on the HTTP endpoints once available.
	- Avoid `PATCH` semantics; when writes are re-enabled, expect full-object `PUT` with explicit rules from the guide.
	This section is intentionally minimal and versioned with the repository so that agents and contributors have a stable fallback when the live guide endpoint or conversational services are unavailable.

[Copilot]

Hard-coding an environment-specific cloud URL in the markdown reintroduces drift risk (URL changes require a doc update). Consider instructing readers to supply the base URL via an env var (e.g., $env:EVA_MODEL_BASE) or referencing a stable DNS alias, so the “one instruction” file stays stable even if infra endpoints rotate.

Suggested change

	# Cloud (production)
	$base = "https://msub-eva-data-model.victoriousgrass-30debbd3.canadacentral.azurecontainerapps.io"
	# Cloud (production) - set EVA_MODEL_BASE env var to your cloud base URL
	$base = $env:EVA_MODEL_BASE