Authoring & Integration
Create portable Knowledge views and choose the correct Work or Review channel using the current public contracts. This profile is public guidance; authenticated context and current authority refine what is available in a Workspace.
Profile orivelaiq-public-authoring 1.3.0 · sha256:b901c3bab9f73e89956eb476819e0d1a341f40660ff43cb0cd8222273151da62
Choose your authoring channel
For a Knowledge view, author a compatible Markdown, SVG or HTML file in an authorized configured Source. For continuing Work, an authenticated MCP agent may edit an authorized Topic with mutate_work, or an external author may prepare portable Work Repository JSON for the Human PLAN → Preview → APPLY path. For an External Response, use exported Review Exchange context and separately authorized Git access. Source choice: optional OrivelaIQ Home with separate authorized Markdown writing, or independent external GitHub with its own source authority. Home is per-account admin-enabled; an Owner may separately grant an eligible Human Collaborator access to a Repository. OIQ Knowledge/Work, Workspace membership and each Human's Home AI connection remain separate.
After signing in, an accessible Workspace can provide an Effective Workspace Profile through the application or read_workspace_authoring_profile. Authorized administrators have a separate Admin Configuration view and read_workspace_admin_profile. Both refine this Public Baseline; current Topic owner/member or Admin rights separately govern direct MCP Work mutations.
Connected AI / MCP
Use an authenticated personal AI connection for current Workspace context and authorized direct Work changes. The public repository authoring route remains available without a connection.
MCP endpoint: /api/mcp. OAuth protected resource metadata. Connection scope: mcp:access.
- MCP requires a personal AI connection authenticated as a current active Human. Connect to /api/mcp using the installation’s OAuth resource metadata. New consent uses mcp:access; valid legacy grants remain connection-compatible. Connection consent and tool visibility grant no Workspace, Topic, administration or Git rights.
- A connected agent can read_public_authoring_profile, read_public_contract_registry and read_public_contract without Web access. read_public_changes supplies the same repository-owned release impacts, audiences, breaking and action-required information as the public Changes JSON.
- Use list_visible_workspaces and read_workspace_authoring_profile for the current readable Workspace context. read_workspace_admin_profile additionally requires current Admin authority; a visible tool may return forbidden. These reads expose no authentication secrets.
- For direct Work, use list_work_topics and read_work_topic. The Topic response identifies the current authority as admin, owner or member. Owners and Admins manage the Topic; current members may edit its children. Workspace read membership alone does not grant Topic mutation rights.
- Only with current applicable Topic rights, invoke mutate_work with a fresh UUID requestId and the expectedRevision from a fresh read_work_topic result. Existing-topic actions also require topicId. create_topic omits topicId and expectedRevision. Select current artifacts through read_work_artifact_catalog before add_reference and retain the exact view/projectionId.
- On an uncertain transport outcome, retry the identical request; read_work_receipt can recover its durable receipt. A revision_conflict applies no mutation: reread the Topic, reassess the action and use a deliberate new requestId. Current server authority is checked on every operation and receipt replay, without reconnect.
- mutate_work edits Work only. It has no delete_item or delete_entry action; removal actions cover references and relations. Entry type remains immutable, and only CLARIFICATION_POINT has open/closed state. Topic lifecycle and Item knowledgeContextExposure are existing visibility controls, not deletion.
- The Work Repository JSON route remains a separate external authoring/import channel. Neither direct Work mutation nor Knowledge access publishes Source content, imports Review responses, writes Git or executes external agents. A client may independently suppress or confirm writes; current server-side Human and resource rights remain the authorization boundary.
Pinned compatible contracts
| Contract | Version | Canonical representation |
|---|---|---|
| Work Repository | 0.1 | Read complete canonical files |
| Review Exchange | 1.0.0 | Read complete canonical files |
| Artifact Navigation | 1 | Read complete canonical files |
| Interactive HTML authoring | Current guidance; digest identifies content | Read complete canonical files |
Each representation includes its exact source digests. Existing contract versions keep their own semantics; the Public Authoring Profile pins the compatible set.
Profile compatibility and exact snapshot identity
profileVersion describes the semantic compatibility of this authoring guidance, independently of Product releases and the underlying contract versions. An incompatible profile shape or authoring rule requires a major increment; compatible capabilities or fields require a minor increment; clarifications or corrections that retain compatibility require a patch increment. Evidence-only changes may change profileDigest without changing profileVersion when the profile shape, authoring rules and compatible contract pins remain unchanged. Pin an exact snapshot with profileId + profileVersion + profileDigest; a version alone is not content identity. At one installation, Discovery profile.digest, Bootstrap profileDigest, the HTTP Public Profile profileDigest and MCP read_public_authoring_profile profileDigest must agree. Compare the representations available to your client; compare MCP only when connected. Public guidance requires no MCP authentication, and MCP-only or offline use requires no Web access. For offline use, pin the included identities and obtain a fresh profile before later connected use. If available representations differ, reread the compared representations once to refresh a potentially stale snapshot. If disagreement persists, stop and reject mixing those snapshots; do not infer compatibility or select one digest silently. Verify each pinned contract against its own contractDigest, not against profileDigest.
Publish through a configured Source
An authorized administrator configures source selection, artifact types, ordered include/exclude rules and navigation assignment. The current Git-backed content path supports Markdown (.md), SVG (.svg) and HTML (.html). Exclusions apply before a matched artifact is loaded. Authors should use simple supported patterns: **/*.md, **/*.svg, **/*.html, docs/**/*.md, docs/*.md or exact relative paths. Patterns are the current bounded source matcher, not a promise of every glob feature. Work repository JSON is separate structured import data, not indexed Knowledge.
Index availability and controlled failures
Readers browse prepared indexes, not a live repository or whole-content search. Stable and Dynamic are immutable view selectors; display labels may vary. Successful indexing publishes a complete validated projection atomically. A failed run preserves the previous successful projection. A candidate above the configured artifact byte limit is omitted with a too_large diagnostic: no truncated content, placeholder artifact, navigation item or search document is created. Its Grounding targets remain unresolved. Other unsafe load, integrity, source/revision and persistence failures remain fatal. Ask an authorized administrator to inspect diagnostics, reduce content or correct rules, then reindex.
Use the supported Markdown subset
The current reader supports headings #, ## and ###, paragraphs, hyphen bullet lists, bold, inline code, triple-backtick fenced code, pipe tables, inline [label](reference) links and  images. YAML front matter is hidden from the reader. A leading H1 matching the reader title is suppressed; H2/H3 headings provide the outline. Raw HTML is escaped. Do not depend on full CommonMark/GFM, ordered or nested lists, italics, task lists, block quotes, math or executable Markdown. Language tags on fences do not promise syntax highlighting.
Links, SVG and image references
Use source-relative indexed paths for local Markdown/HTML/SVG links. Resolution uses the current authorized loaded index; unresolved local links remain passive text. Heading fragments are compatibility addresses, not stable semantic-node identity. Local image embedding currently resolves indexed SVG only, through its protected content reference and passive <img> rendering; SVG is never injected into the application DOM. Unresolved/blocked image references show a placeholder. HTTP(S) remote images currently render as images; prefer indexed SVG for portable authored content. HTTP(S) and mailto links open separately; unsafe schemes are blocked. Interactive HTML has stricter self-contained, no-network rules.
Static and interactive HTML
HTML defaults to static sandboxed rendering with scripts disabled. Interactive HTML requires explicit Source-level Admin opt-in; an artifact cannot enable its own policy. Author one self-contained HTML file with inline CSS/JavaScript/data, inline SVG or data images/fonts and a system-font fallback. No CDN, remote stylesheet/font/image/API, fetch/XHR/WebSocket, browser storage, form submission, popups, downloads, parent DOM/data or direct top-level navigation may be required. Scripts run only in an isolated allow-scripts frame without same-origin. Include semantic keyboard controls, visible focus, meaningful initial content, accessible labels, reduced-motion support where needed and usable standalone fallback.
Persist the right identity
A source path and documentId are locators/aliases/evidence; artifact.id and projectionId are concrete runtime selectors, not durable Knowledge identity. Do not invent, persist or hard-code those runtime IDs into repository Work definitions. Source-owned knowledge_object_id establishes the current bounded canonical Markdown identity when explicitly declared. Keep it stable on move/rename/title edit and never reuse it for unrelated Knowledge. Review Exchange uses UUID public IDs, never internal rv* IDs. Work externalKey is configuration-scoped import identity, not internal Domain identity.
Declare direct Current Grounding
Canonical Git-backed Markdown in a non-companion canonical Source may declare top-level knowledge_object_id and optional grounded_by in YAML front matter. Use lower-case UUID URNs (UUID versions 1–8, RFC variant), and at most 128 unique grounded_by strings of the same syntax. References resolve directly within the same ContentSource Public ID and authorized projection; no cross-Source lookup or transitive inference occurs. grounded_by requires identity. Duplicate IDs/references, self-reference, malformed participating YAML or identity fail the indexing run. Use unique YAML mapping keys; no aliases, anchors, tags or merge keys. Unknown/excluded/unavailable targets remain generic unresolved. grounds is derived, never authored. Translation declarations do not establish graph authority.
Optional whole-artifact snapshot evidence
Canonical Git-backed Markdown may declare kind: snapshot and snapshotAt: an RFC-3339 timestamp in top-level YAML front matter. A participating declaration must be complete and valid; aliases, anchors, tags and merge keys are rejected. These fields describe a whole-artifact snapshot observation. They do not establish row/claim/section correctness, create a governed Knowledge Time State or confer authority. Invalid participating metadata fails indexing and preserves the previous successful projection.
Current localization and Rendition limits
Durable translations stay externally owned and read-only to OrivelaIQ. The implemented Translation Manifest v1 maps document_id, source_path and target_path plus source revision/blob, locale, repository-owned status/currency, review evidence and source findings. A configured companion Source requires explicit canonical binding and manifest mapping; arbitrary translated filenames or similar titles do not establish equivalence. Keep status/currency claims distinct from technical source drift. Current UI can group document-level language variants and select an available preferred language. Translation is Rendition, not Knowledge State; meaning-changing localization is not a Rendition of the same Knowledge Object. Governed State binding remains unresolved without evidence. Use Translation Manifest v1 for current authoring. Manifest v1 requires schema_version: 1 and root pilot_id, canonical_repository, canonical_branch, canonical_language, target_locale, source_audit (repository/path/pull_request), terminology_version and a nonempty translations list. Each mapping requires document_id, source_path, target_path, source_commit, source_blob_sha, status, currency, review_evidence and a nonempty source_findings list; translation_commit is optional. target_path must start with target_locale/. Status is experimental, draft, reviewed, approved or rejected; currency is current, stale or unknown. review_evidence is a safe relative path with persistent fragment. Source/target paths must be matched by the configured canonical/companion rules. Unknown fields, duplicate document/path mappings and YAML aliases/anchors fail validation.
Author portable Work Repository JSON
Use Work Repository 0.1: one topic.json and items/*.json per configured root; Topic → Item → Entry, with stable externalKey values. Entry types are exactly INSIGHT, CLARIFICATION_POINT, DECISION and RESULT. Labels belong to Item; relatesTo links Entry externalKeys within the same Topic. Entry type is immutable: use a new key to retype. Clarification open/closed state, membership, internal IDs/revisions and receipts remain runtime-owned. Portable artifactRefs use workspaceAlias,sourceKey,path,view (stable or dynamic); omit references until an authorized configured target can resolve them. Manual Human PLAN → Preview → APPLY rechecks schema, cross-file links, access, exact projections, freshness and conflicts. Schema validity alone is not APPLY readiness. Reimport preserves clarification state; source removal does not delete Work. No automatic import or Git write is supplied.
Contribution and External Response use different channels
Capture a Contribution in Knowledge context through the available authorized product interaction. Contribution is raw provenance, not a typed Work Result and not the External Response write channel. A controlled Review Exchange produces a Review Package/Item and exact exported context. An external Human/AI authors an External Response in that exchange repository with separately authorized Git access, then the authorized import/review path brings it into Knowledge context. MCP Knowledge/Work access grants no Git write and is not a replacement feedback-response channel. Authorship claims are provenance, never authentication; repeated concerns do not by themselves become Findings.
Author an External Response against an export
Use Review Exchange 1.0.0. The response pair lives at installations/<ownerInstallationId>/review-packages/<packagePublicId>/items/<itemPublicId>/responses/<newResponsePublicId>/response.yaml and response.md. Use exact exported UUID v4 public IDs/revisions/context hash in basedOn; allocate a new response UUID. Both files share validated external authorship authority; the package owner has no implicit response write permission. Response metadata/bodies are create-only. Use the actual exported owner/package/item/context values, a distinct external exporter installation and matching authorship.installationId. Validate the envelope and Markdown front matter using the included schemas; preserve passive body content. Current import additionally requires complete item/context BasedOn. Stale/conflicting inputs receive controlled review treatment, never silent re-anchoring. Read canonical path/authority and import checks before any separately authorized Git write.
OrivelaIQ Home · English
OrivelaIQ Home is an optional OIQ-operated source alongside independent external GitHub. Inside OIQ and in Human-directed AI answers call it Home; OIQ Home is the branded short name. One Home pairs one canonical repository with its real home Workspace and default Source; one Human may have several Homes (Your Homes / Your Home). Home requires per-account administrator enablement. A separately authorized Home AI connection may write permitted Markdown source content; the OIQ Knowledge/Work MCP connection is independent and grants no Home write access. Writing does not update the fixed Stable view: committed Markdown may already be indexed and read in Dynamic. An existing pinned Stable remains unchanged until an authorized Human deliberately replaces the pin. Without a Stable pin, Dynamic may be the default. This is not a new approval workflow. Preserve technical managed_git, mgit.use, oiq-045/1, tool names, schemas and OAuth resources. No new consent, grant or reconnect is needed merely for the name. Connector display names belong to their App/client registration owner; Home OAuth and tool descriptions belong to the independently deployed M.Git service. Public guidance cannot verify a client title or its installed revision. Home ownership and a separately granted shared Repository are different: use the collaboration guidance below. Do not promise browser upload/editing, unrestricted export/delete, retention, hosting geography or legal ownership.
OrivelaIQ Home · Deutsch
OrivelaIQ Home ist eine optionale, von OIQ betriebene Source neben unabhängigem externem GitHub. Innerhalb von OIQ und in AI-Antworten an Humans heißt sie Home; die kurze Markenform ist OIQ Home. Ein Home verbindet ein kanonisches Repository mit seinem echten Home-Workspace und der Standard-Source; ein Human kann mehrere Homes haben (Deine Homes / Dein Home). Die Administration muss Home für jedes Konto freischalten. Eine getrennt autorisierte Home-AI-Verbindung kann erlaubte Markdown-Quelldateien schreiben; die OIQ-Knowledge/Work-MCP-Verbindung ist unabhängig und erteilt keinen Home-Schreibzugriff. Schreiben ist nicht die Freigabe des festen Stands: Geschriebenes Markdown kann bereits indexiert und in Dynamic gelesen werden. Ein bestehender fester Stable-Stand bleibt unverändert, bis ein berechtigter Human den Pin ausdrücklich ersetzt. Ohne Stable-Pin kann Dynamic die Standardansicht sein. Das ist kein neuer Freigabeprozess. Technische managed_git, mgit.use, oiq-045/1, Tool-Namen, Schemas und OAuth-Ressourcen bleiben erhalten. Allein die Benennung erfordert keine neue Zustimmung, Berechtigung oder Verbindung. Den sichtbaren Connector-Namen verantwortet der App-/Client-Registrierungsinhaber; Home-OAuth und Tool-Beschreibungen verantwortet der unabhängig bereitgestellte M.Git-Dienst. Öffentliche Hilfe bestätigt keinen Client-Titel oder installierten Stand. Home-Eigentümerschaft und ein separat freigegebenes Repository sind verschieden: Beachte die folgende Anleitung zur Zusammenarbeit. Versprich keine Browser-Uploads oder Editoren, uneingeschränkten Export/Löschung, Aufbewahrung, Hosting-Geografie oder rechtliches Eigentum.
Shared Repository authoring · English
An Owner can use Participants to grant Collaborator access to one specific existing active OIQ Human whose account is already administrator-enabled for Home (mgit.use). Enter the recipient's exact email, verify the displayed identity and confirm the grant. An unavailable match does not reveal whether an account exists. Collaborator means repository-scoped Markdown read/write access; the original Owner keeps ownership and alone manages Participants. The recipient uses their own separately authorized Home AI/MCP connection or authenticated Home REST access. A shared Repository is not the recipient's own Home and creates no OIQ Workspace membership, protected Knowledge/Work access, Source/Index rights or Stable publication rights. OIQ's existing independent Indexer grant can update Dynamic automatically after a valid commit; an existing Stable pin stays fixed. Current active-account eligibility and repository grants are checked on every protected operation. After revoke, the next protected read/write operation is denied even with an already connected client; an operation already admitted at the final pre-push authorization may finish and remains historical fact. Removing administrator enablement also blocks use; it does not erase the persisted grant. Restore access only through current explicit authority. No Deputy, new global role or browser Markdown editor is supplied. Availability depends on the connected Home service; older services keep existing Owner use without Participants.
Gemeinsam im Repository schreiben · Deutsch
Ein Owner kann unter Teilnehmer einem bestimmten bestehenden, aktiven OIQ-Human Bearbeiter-Zugriff erteilen, dessen Konto die Administration bereits für Home (mgit.use) freigeschaltet hat. Gib die genaue E-Mail-Adresse ein, prüfe die angezeigte Identität und bestätige die Berechtigung. Ein nicht verfügbarer Treffer verrät nicht, ob ein Konto existiert. Bearbeiter bedeutet Markdown-Lese-/Schreibzugriff auf dieses Repository; der ursprüngliche Owner bleibt Eigentümer und verwaltet allein die Teilnehmer. Der Empfänger nutzt seine eigene, getrennt autorisierte Home-AI-/MCP-Verbindung oder authentifizierten Home-REST-Zugriff. Ein freigegebenes Repository ist nicht das eigene Home des Empfängers und erzeugt keine OIQ-Workspace-Mitgliedschaft, keinen geschützten Knowledge-/Work-Zugriff, keine Source-/Index-Rechte und kein Recht zur Stable-Veröffentlichung. OIQ kann Dynamic nach einem gültigen Commit über seine bestehende unabhängige Indexer-Berechtigung automatisch aktualisieren; ein bestehender Stable-Pin bleibt fest. Aktueller Kontostatus, Freischaltung und Repository-Berechtigung werden bei jeder geschützten Operation geprüft. Nach Widerruf wird die nächste geschützte Lese-/Schreiboperation auch bei bestehender Client-Verbindung verweigert; eine bei der letzten Prüfung vor dem Push bereits zugelassene Operation kann noch abschließen und bleibt Historie. Entzug der administrativen Freischaltung sperrt die Nutzung ebenfalls, löscht aber keine gespeicherte Berechtigung. Zugriff kehrt nur mit aktueller ausdrücklicher Berechtigung zurück. Es gibt keinen Stellvertreter, keine neue globale Rolle und keinen Browser-Markdown-Editor. Die Verfügbarkeit hängt vom verbundenen Home-Dienst ab; ältere Dienste erhalten die bestehende Owner-Nutzung ohne Teilnehmerverwaltung.
Current limitations
- Knowledge content is read from configured Sources. Authors update repository files through separately authorized repository tools.
- The product does not execute external agents.
- Current Markdown is a bounded subset. Interactive HTML requires Source-level Admin opt-in and remains self-contained.
- Current localization uses Translation Manifest v1. A translation does not establish a governed Knowledge State or semantic-node equivalence.
- Review import authorship limitation: ai_assisted and unknown remain rejected by the current import path.
- No public guidance, contract, identifier, discovery or transfer grants access.
Self-contained interactive Knowledge map
Open standalone to filter local content; a registered interactive host progressively enables mediated navigation.
Included file: contracts/public-authoring/examples/interactive-map.html · sha256:608f21fcca71d23f472bfb72df0e528f6c136b35a99e6c35295d2a509e17f68a
View complete example — save as .html and open standalone
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>Service handover knowledge map</title>
<style>
:root{color-scheme:light dark;font-family:system-ui,sans-serif;line-height:1.55}body{margin:0;background:#f4f7fa;color:#172b3a}main{max-width:52rem;margin:auto;padding:clamp(1rem,4vw,2.5rem)}h1{line-height:1.2}article{background:white;border:1px solid #cad5dd;border-radius:.8rem;padding:1rem;margin:1rem 0}label{display:block;font-weight:650}input,button{font:inherit;border:1px solid #526b7d;border-radius:.35rem;padding:.65rem;background:white;color:#172b3a}input{box-sizing:border-box;width:100%;max-width:34rem}button{cursor:pointer;margin:.5rem 0}button:hover{background:#e6f0f7}:focus-visible{outline:3px solid #176dad;outline-offset:3px}code{overflow-wrap:anywhere}small{display:block;color:#425b6c}[hidden]{display:none}#status{min-height:3rem}footer{border-top:1px solid #cad5dd;margin-top:2rem;padding-top:1rem}@media(prefers-color-scheme:dark){body{background:#12202b;color:#e6eef4}article,input,button{background:#1e3342;color:#e6eef4}small{color:#bdcfdb}button:hover{background:#2b4a61}}@media(prefers-reduced-motion:reduce){*{scroll-behavior:auto}}
</style>
</head>
<body>
<main>
<p>Self-contained interactive Knowledge view</p>
<h1>Service handover knowledge map</h1>
<p>Read the summaries here, filter them locally, and use the visible references to find supporting Knowledge. Host navigation is optional.</p>
<label for="filter">Filter the embedded summaries</label>
<input id="filter" type="search" placeholder="Try contact or principles" aria-controls="cards">
<p id="count" aria-live="polite">3 summaries</p>
<section id="cards" aria-label="Knowledge summaries">
<article data-search="handover guide contact">
<h2>Handover guide</h2><p>Record the service contact and explain when to use it. Keep responsibilities visible during a handover.</p>
<small>Reference: <code>docs/service-handover.md</code></small>
<button type="button" data-path="docs/service-handover.md">Open handover guide in host</button>
</article>
<article data-search="service principles ownership">
<h2>Service principles</h2><p>Assign clear ownership before extending procedures. Use these principles as the factual basis for the guide.</p>
<small>Reference: <code>docs/service-principles.md</code></small>
<button type="button" data-path="docs/service-principles.md">Open service principles in host</button>
</article>
<article data-search="contact catalogue search">
<h2>Find a contact</h2><p>If a precise file path is uncertain, use the current Workspace search to find the service contact.</p>
<small>Search reference: <code>service contact</code></small>
<button type="button" data-query="service contact">Search for service contact in host</button>
</article>
</section>
<p id="empty" hidden>No summaries match. Clear the filter to show all summaries.</p>
<p id="status" role="status" aria-live="polite">Standalone mode: all summaries and references remain available. Host navigation becomes available only after a supported handshake.</p>
<noscript><p>JavaScript is disabled. All summaries and references remain visible; local filtering and host navigation are unavailable.</p></noscript>
<footer>Example references are illustrative. Replace them with exact indexed current-Workspace paths or a meaningful search query before publishing.</footer>
</main>
<script>
(() => {
'use strict';
const protocol = 'orivelaiq.artifact.v1';
const status = document.getElementById('status');
const pending = new Map();
let hostReady = false;
let sequence = 0;
const attempts = [];
const show = text => { status.textContent = text; };
const fallback = (reference, reason) => show(reason + ' Reference: ' + reference + '. The summary remains available here.');
window.addEventListener('message', event => {
if (window.parent === window || event.source !== window.parent) return;
const data = event.data;
if (!data || typeof data !== 'object' || data.protocol !== protocol) return;
if (data.type === 'host-ready' && Array.isArray(data.capabilities) && data.capabilities.includes('navigate')) {
hostReady = true;
show('Host navigation is available. Choose a Knowledge reference to request navigation.');
return;
}
if (data.type !== 'navigate-result' || !['accepted', 'not-found', 'denied'].includes(data.status)) return;
const request = pending.get(data.requestId);
if (!request) return;
clearTimeout(request.timer);
pending.delete(data.requestId);
if (data.status === 'accepted') show('The host accepted navigation to ' + request.reference + '.');
else fallback(request.reference, data.status === 'not-found' ? 'The host could not resolve this reference.' : 'The host did not allow this request.');
});
document.querySelectorAll('button[data-path],button[data-query]').forEach(button => {
button.addEventListener('click', () => {
const target = button.dataset.path ? {kind:'artifactPath',path:button.dataset.path} : {kind:'search',query:button.dataset.query};
const reference = button.dataset.path || button.dataset.query;
if (!hostReady) { fallback(reference, 'Host navigation is unavailable.'); return; }
const now = Date.now();
while (attempts.length && now - attempts[0] >= 2000) attempts.shift();
if (attempts.length >= 5) { fallback(reference, 'Please wait before requesting another navigation.'); return; }
attempts.push(now);
const requestId = 'map-' + (++sequence) + '-' + now;
const timer = setTimeout(() => {
pending.delete(requestId);
fallback(reference, 'The host request timed out.');
}, 2000);
pending.set(requestId, {reference, timer});
show('Requesting host navigation to ' + reference + '…');
window.parent.postMessage({protocol,type:'navigate',requestId,userActivated:true,target}, '*');
});
});
const filter = document.getElementById('filter');
const cards = Array.from(document.querySelectorAll('article[data-search]'));
filter.addEventListener('input', () => {
const query = filter.value.trim().toLowerCase();
let visible = 0;
cards.forEach(card => {
card.hidden = !((card.dataset.search + ' ' + card.textContent).toLowerCase().includes(query));
if (!card.hidden) visible++;
});
document.getElementById('count').textContent = visible + (visible === 1 ? ' summary' : ' summaries');
document.getElementById('empty').hidden = visible !== 0;
});
})();
</script>
</body>
</html>
Complete Work Topic and Item
Schema-valid repository files without runtime Artifact references.
Included file: contracts/public-authoring/examples/work-repository.json · sha256:5b5d6eb1c5aee5aa7a56349d4e068741b23a9636b41704b788b2af85a6d4ece7
View complete example
{
"files": [
{
"path": "topic.json",
"content": {
"schemaVersion": "0.1",
"externalKey": "service-handover",
"title": "Improve service handover",
"description": "Continue useful findings and clarification."
}
},
{
"path": "items/01-handover.json",
"content": {
"schemaVersion": "0.1",
"externalKey": "handover-guide",
"topicExternalKey": "service-handover",
"title": "Make the handover guide usable",
"labels": [
"handover"
],
"knowledgeContextExposure": "include",
"entries": [
{
"externalKey": "contact-observation",
"type": "INSIGHT",
"text": "The handover guide does not explain the first contact."
},
{
"externalKey": "contact-question",
"type": "CLARIFICATION_POINT",
"text": "Clarify which contact belongs in the guide.",
"relatesTo": [
"contact-observation"
]
},
{
"externalKey": "contact-approach",
"type": "DECISION",
"text": "Record the service contact before extending the guide."
},
{
"externalKey": "review-result",
"type": "RESULT",
"text": "The review identified the contact as the next clarification.",
"relatesTo": [
"contact-question"
]
}
]
}
}
]
}
External Response file pair
Schema/runtime-valid illustrative values. Replace identities and BasedOn with exact authorized export context before authoring.
Included file: contracts/public-authoring/examples/external-response.json · sha256:8d0ee43f7e22f69c8cef396f1914c41687f2e24501d63fc5ca280c4a7c09a656
View complete example
{
"illustrativeOnly": true,
"ownerInstallationId": "11111111-1111-4111-8111-111111111111",
"replacementRule": "Use exact public IDs, revisions, exportedAt and contextHash from the authorized current export; allocate a new response UUID and supply truthful separately authorized external installation/authorship. Recompute the bodyDigest for exact response.md bytes ending in one newline.",
"files": [
{
"path": "installations/11111111-1111-4111-8111-111111111111/review-packages/22222222-2222-4222-8222-222222222222/items/33333333-3333-4333-8333-333333333333/responses/44444444-4444-4444-8444-444444444444/response.yaml",
"content": "{\n \"schemaVersion\": \"1.0.0\",\n \"entityType\": \"response\",\n \"exportedAt\": \"2026-10-07T00:00:00Z\",\n \"exporter\": \"55555555-5555-4555-8555-555555555555\",\n \"entity\": {\n \"publicId\": \"44444444-4444-4444-8444-444444444444\",\n \"revision\": 1,\n \"createdAt\": \"2026-10-07T00:00:00Z\",\n \"updatedAt\": \"2026-10-07T00:00:00Z\",\n \"origin\": {\n \"type\": \"review_exchange\",\n \"installationId\": \"55555555-5555-4555-8555-555555555555\"\n },\n \"packagePublicId\": \"22222222-2222-4222-8222-222222222222\",\n \"itemPublicId\": \"33333333-3333-4333-8333-333333333333\",\n \"responseType\": \"clarification\",\n \"authorship\": {\n \"type\": \"ai\",\n \"installationId\": \"55555555-5555-4555-8555-555555555555\",\n \"displayName\": \"External review assistant\",\n \"modelName\": \"example-model\"\n },\n \"basedOn\": {\n \"packagePublicId\": \"22222222-2222-4222-8222-222222222222\",\n \"packageRevision\": 1,\n \"itemPublicId\": \"33333333-3333-4333-8333-333333333333\",\n \"itemRevision\": 1,\n \"contextRevision\": 1,\n \"contextHash\": \"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\n \"exportedAt\": \"2026-10-07T00:00:00Z\"\n },\n \"bodyDigest\": \"sha256:c714ced7caa298250f53039c6addc5614e3bec559cc6a50658f0faaf573876d9\"\n }\n}\n"
},
{
"path": "installations/11111111-1111-4111-8111-111111111111/review-packages/22222222-2222-4222-8222-222222222222/items/33333333-3333-4333-8333-333333333333/responses/44444444-4444-4444-8444-444444444444/response.md",
"content": "---\n{\n \"schemaVersion\": \"1.0.0\",\n \"publicId\": \"44444444-4444-4444-8444-444444444444\",\n \"itemPublicId\": \"33333333-3333-4333-8333-333333333333\",\n \"responseType\": \"clarification\",\n \"status\": \"submitted\",\n \"authorship\": {\n \"type\": \"ai\",\n \"installationId\": \"55555555-5555-4555-8555-555555555555\",\n \"displayName\": \"External review assistant\",\n \"modelName\": \"example-model\"\n },\n \"basedOn\": {\n \"packagePublicId\": \"22222222-2222-4222-8222-222222222222\",\n \"packageRevision\": 1,\n \"itemPublicId\": \"33333333-3333-4333-8333-333333333333\",\n \"itemRevision\": 1,\n \"contextRevision\": 1,\n \"contextHash\": \"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\n \"exportedAt\": \"2026-10-07T00:00:00Z\"\n },\n \"createdAt\": \"2026-10-07T00:00:00Z\"\n}\n---\n# Clarification\n\nThe guide should name the service contact and explain when to use it.\n"
}
]
}
Canonical Markdown Grounding
A direct same-Source declaration; the referenced target must declare the matching identity.
Included file: contracts/public-authoring/examples/grounding.md · sha256:626ad08d2419a238670a0d4ff240d2b17aee22a6488127af17b0a7cac3db6129
View complete example
---
knowledge_object_id: urn:uuid:11111111-1111-4111-8111-111111111111
grounded_by:
- urn:uuid:22222222-2222-4222-8222-222222222222
---
# Service handover
This guide is grounded by the separately identified service principles in the same canonical ContentSource.
Translation Manifest v1
Runtime-valid document-level companion mapping with illustrative repository/ref/path evidence. Configuration must match the canonical and companion Sources; translations remain externally owned.
Included file: contracts/public-authoring/examples/localization-v1.json · sha256:1cd0c45939296d6463c22283a0eac87b2f285e138e61b491bea818f8178f0c48
View complete example
{
"illustrativeOnly": true,
"replacementRule": "Use actual canonical repository, configured ref, source revision/blob and persistent review evidence. Do not copy illustrative hashes as evidence. Keep source/target paths matched by authorized Source rules.",
"files": [
{
"path": "translation-manifest.yml",
"content": "schema_version: 1\npilot_id: service-guide-de-DE\ncanonical_repository: example/service-knowledge\ncanonical_branch: main\ncanonical_language: en\ntarget_locale: de-DE\nsource_audit:\n repository: example/service-knowledge\n path: governance/source-audit.md\n pull_request: 1\nterminology_version: \"1.0\"\ntranslations:\n - document_id: service.handover\n source_path: docs/service-handover.md\n target_path: de-DE/docs/service-handover.md\n source_commit: aaaaaaaa\n source_blob_sha: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\n status: draft\n currency: unknown\n review_evidence: governance/translation-review.md#handover\n source_findings:\n - canonical-source-review-pending\n"
},
{
"path": "docs/service-handover.md",
"content": "# Service handover\n\nRecord the service contact before extending the guide.\n"
},
{
"path": "de-DE/docs/service-handover.md",
"content": "# Serviceübergabe\n\nErfasse den Servicekontakt, bevor du den Leitfaden erweiterst.\n"
}
]
}
Offline and integrity checks
Give the Full Public Transfer JSON to an agent without Web/MCP access. It includes profile/contract identities, all canonical contract files and schema dependencies, complete examples, rules, limitations, generation time and release changes. Parse schema content from contracts[].files and resolve relative schema references against the included path/$id; the included schemas require no network lookup. Replace illustrative External Response values with exact authorized export context before any separately authorized Git write. This snapshot grants no access and cannot assert current Workspace capability.
All digest values use SHA-256 over UTF-8 bytes, expressed as sha256: followed by lower-case hexadecimal. A raw file/source digest covers the exact UTF-8 bytes of its content, including whitespace and newlines, without text or Unicode normalization. For structured identities, canonical JSON recursively sorts object keys lexically, retains array order, and serializes compact JSON without text or Unicode normalization. The Public Authoring Profile hashes its complete projected object after removing only the top-level profileDigest field. The Contract Registry hashes its complete projected object after removing only the top-level registryDigest field. Each contract hashes exactly the canonical object {id,version,sources:[{path,digest}]}: use the contract id and version (including null where present), with sources in the order listed for that contract in the registry. Full Transfer hashes its complete projected object after removing only the top-level digest field; retain all nested profile, registry, contract and file digest fields. Evidence-only hashes cannot be independently rehashed offline when their raw bytes are omitted; this intentional boundary keeps implementation details private. Snapshot integrity does not establish publisher authenticity or currentness. The snapshot records its generation time; obtain a fresh profile before later connected use.
Stable Public Discovery · Contract Registry · Current release and changes