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 exposes so an AI agent can discover and use it end to end from just its URL, organized as five independently adoptable layers:

Composition: a /.well-known/ic-architecture JSON manifest listing every canister with its role, served as real JSON at the extensionless well-known path and generated at deploy time.
Interface: the canister's public candid:service metadata.
Behavior: a getApiDoc / get_api_doc query method returning a markdown guide to the units, lifecycle, and gotchas the types cannot convey.
Data: a self-describing OQL schema + execute query surface for data-rich apps, with the Result payload shape given in Candid.
Identity: 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.

The page closes with a deployment checklist and acceptance tests (including icp canister metadata for fetching candid:service).

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

Written declaratively: each layer states what an app exposes, without "proposed/standard/convention" labels or rationale asides.
Cross-links to Asset canister (.well-known static serving and SPA routing), Custom domains (the ic-domains well-known pattern), Internet Identity (derivationOrigin and alternative origins), and the Candid interface guide.
npm run build passes. Prose follows the docs style rules (no em-dashes, US spelling, sentence-case headings, relative .md links).
One caveat carries an in-source verification note: the OQL Result cell value type is assumed text pending confirmation.

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.

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.

raymondk

After discussing with @aterga this is the pragmatic way forward.
I wanted to try to use the same file for remixing information but we agreed to use different files instead of overloading the .well-known/ic-architecture.

⚠️ if we ever introduce canister groups, I think it will make more sense to serve this information from the canister group instead.

The execute Result cells carry a type-tagged variant value, not text. Verified against the imcp2 OQL primer (static/oql-primer.md): Cell = record { name : text; value : variant }. Drop the verification note.

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