docs: add Service discoverability guide under Frontends by aterga · Pull Request #323 · dfinity/developer-docs

aterga · 2026-07-24T17:35:19Z

Summary

Adds a new guide, Service discoverability, under guides/frontends/, placed immediately after Custom domains in the sidebar.

The page describes what a canister app should expose so an AI agent can discover and use it end to end from just its URL, organized as five independently adoptable layers:

Composition (proposed): a /.well-known/ic-architecture JSON manifest listing every canister and its role, served at the extensionless well-known path and generated at deploy time.
Interface (standard): the canister's public candid:service metadata.
Behavior (convention): a getApiDoc / get_api_doc query method returning a markdown guide to units, lifecycle, and gotchas the types cannot convey.
Data (convention): a self-describing OQL schema + execute query surface for data-rich apps.
Identity (proposed): declaring the effective Internet Identity derivation origin in /.well-known/ii-derivation-origin, and why the ii-alternative-origins file is the inverse relation and must not be read backwards.

It also covers discovery anti-patterns (HTML-embedded metadata, the forgeable x-ic-canister-id header, runtime cookie config, JS-bundle mining, SPA catch-all responses), a precedence table of who produces what, a deployment checklist, and acceptance tests.

Changes

New page: docs/guides/frontends/service-discoverability.md (sidebar.order: 3).
docs/guides/frontends/certification.md: sidebar order 3 → 4.
docs/guides/frontends/frameworks.md: sidebar order 4 → 5.

Notes

Standards vs. proposed conventions are labeled per section so readers know which mechanisms exist today (candid:service, ii-alternative-origins) and which are proposed.
Cross-links to Asset canister (.ic-assets.json5 / SPA routing), Custom domains (the ic-domains well-known pattern), Internet Identity (derivationOrigin / alternative origins), and the Candid interface guide.
npm run build passes; the new page builds with no validation warnings. Prose follows the docs style rules (no em-dashes, US spelling, sentence-case headings, relative .md links).

Add a guide describing what a canister app exposes so an AI agent can discover and use it from just its URL, organized as five layers: composition (/.well-known/ic-architecture manifest), interface (candid:service), behavior (getApiDoc), data (OQL), and identity (/.well-known/ii-derivation-origin). Placed after Custom domains; bump Response certification and Frontend frameworks sidebar order to follow.

github-actions · 2026-07-24T17:35:37Z

🤖 Here's your preview: https://soxyi-6iaaa-aaaam-ai2ra-cai.icp0.io

Copilot

Pull request overview

Note: live brand rules (/rules.json) could not be reached, so this review applied the bundled icp-brand-voice rules (authored against brand guide v2.25).

Adds a new frontend guide that defines a structured, layered approach for making canister apps discoverable to AI agents from only an app URL, and updates the Frontends guide ordering so the new page sits after Custom domains.

Changes:

Add Service discoverability guide under docs/guides/frontends/ describing five discovery layers (composition, interface, behavior, data, identity) and anti-patterns.
Adjust Frontends sidebar ordering to insert the new guide after Custom domains.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
docs/guides/frontends/service-discoverability.md	New guide documenting URL-first discovery signals and a deployment/verification checklist for agent consumption.
docs/guides/frontends/certification.md	Sidebar order update to accommodate the new guide in the Frontends sequence.
docs/guides/frontends/frameworks.md	Sidebar order update to accommodate the new guide in the Frontends sequence.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

curl -s exits 0 on an HTTP 404, so the '|| echo default' branch never ran when the ii-derivation-origin file is absent (the documented default case). Use curl -sf so a non-2xx response is treated as an error and the fallback fires.

Address review feedback: the Layer 1 serving rules pinned the specific .ic-assets.json5 rule inline, which is asset-canister-specific. State the requirement generically (serve /.well-known/* as a static file, exempt it from the SPA rewrite) and defer the concrete config to the Asset canister and Custom domains pages already linked.

Address review feedback on Layer 5: split the dense 'well-behaved agent' paragraph into who reads the file (the agent/connector, out of band like curl, not the II frontend during login, so no CORS or special headers) and what it does with it (report both origins alongside the principal so a mismatch is visible; a report in the agent's result, not a console log).

Revise per PR review: declarative voice throughout (drop the proposed/standard/convention status framing and the standards-vs-proposed overview paragraph); trim the intro, drop the 'One way to expose each fact' and 'Anti-patterns' sections, the proposed-convention note, and the precedence table. Reformat the manifest as multi-line JSON with version and name fields (matching the ic-architecture template) and link the demo repo. Give the OQL Result payload a Candid type. Restructure Layer 5 (three-input framing; move the alternative-origins note after the derivation-origin file). Provide the icp canister metadata command in the acceptance tests. Rename the closing section to Related documents.

aterga requested a review from Copilot July 25, 2026 15:24

Copilot started reviewing on behalf of aterga July 25, 2026 15:24 View session

Copilot AI reviewed Jul 25, 2026

View reviewed changes