> For the complete documentation index, see [llms.txt](https://docs.therisk.global/organization/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.therisk.global/organization/standardization/nexus-sovereignty/v.-verifiable-credentials/did-format-human-org-machine-system.md). # DID Format (Human, Org, Machine, System) ## Decentralized Identifiers in the Nexus Sovereignty Framework: DID-Based Identity, Role-Bound Authority, Credential Linkage, Machine Identity, Revocation, and Verifiable Accountability Across Governance Execution ### Why Decentralized Identifiers Matter in NSF Decentralized Identifiers matter because the Nexus Sovereignty Framework operates in a world where governance actions are distributed across humans, institutions, machines, AI agents, secure runtimes, sovereign nodes, community stewards, credential issuers, simulation validators, Project SPV evidence rooms, public-safe reviewers, and regional or national governance bodies. In that environment, every material action must be attributable. A Smart Clause cannot simply “execute.” A clause must execute under a known runtime, a known node, a known governance scope, and a known authority chain. A credential cannot simply “appear.” It must be issued by an identified issuer under a registered schema and revocable status system. A CAC cannot simply be signed by a key. The key must resolve to a governed identity with a role, credential, jurisdiction, and revocation path. This is the role of Decentralized Identifiers, or DIDs. DIDs provide persistent, cryptographically verifiable identifiers for actors and systems without requiring all identity to be controlled by a single central provider. In NSF, DIDs function as identity anchors for authentication, authorization, signing, encryption, credential issuance, runtime attestation, governance participation, audit accountability, and dispute resolution. DIDs are necessary because NSF is multi-agent by design. A human reviewer may sign a simulation review. A national node may issue a CAC. A TEE may sign a runtime attestation. A credential issuer may update status. An AI agent may request a clause execution. A community steward may approve protected knowledge disclosure. A Project SPV evidence room may publish a controlled CAC. A regional consortium may sign a rollup. A public-safe reviewer may approve a redacted output. Each actor needs an identity that can be verified, scoped, delegated, suspended, rotated, and audited. Without DID-based identity, NSF would collapse into platform accounts, email addresses, static API keys, informal administrator roles, unverifiable signatures, and institution-specific user directories. That would make cross-jurisdictional governance weak. It would also make accountability fragile. If a clause output was wrong, a credential was misissued, an AI agent exceeded scope, a node produced invalid attestations, or a public-safe output disclosed protected data, the system would need to know who or what acted, under which authority, and whether that authority was valid at the time. The core doctrine is: **Every material NSF action must be signed by an identifiable actor or system whose DID resolves to active keys, credentialed authority, jurisdictional scope, governance role, revocation status, and audit obligations.** ### DIDs as Identity Anchors, Not Authority by Themselves A DID identifies an actor or system. It does not, by itself, authorize action. This distinction is fundamental. A DID is an identity anchor. Authority comes from credentials, role bindings, governance scope, jurisdiction, issuer status, registry records, law, contract, institutional mandate, community rules, or enterprise authorization. A DID without an active credential may prove who signed something, but not whether they were allowed to sign it. For example, a DID may identify a human analyst. That does not make the analyst a SimulationValidator. A DID may identify a national node. That does not authorize it to execute public health clauses unless it holds the correct node credential. A DID may identify a TEE node. That does not make its CAC valid unless its attestation profile, runtime measurement, and workload scope are approved. A DID may identify an AI agent. That does not allow it to access a controlled evidence room unless it has an active tool-use credential and the request passes policy. A DID may identify a Project SPV evidence room. That does not make its evidence finance-approved. NSF therefore treats DIDs and Verifiable Credentials as inseparable. The DID is the identity root. The VC is the authority statement. The Registry Layer is the status and discovery system. The Audit Layer is the memory of use. The Smart Clause is the policy logic that checks whether the DID and credentials are sufficient for action. This prevents “key equals authority” failure. A signature is only meaningful when the signer’s role is current, scoped, and recognized for the action. ### DID Categories in NSF NSF should define canonical DID categories because different actor classes require different governance, key management, revocation, delegation, and audit rules. A **human DID** identifies a person participating in NSF workflows. Human DIDs may belong to reviewers, analysts, public-safe officers, community stewards, national representatives, credential holders, simulation validators, Project SPV reviewers, or operational actors. Human DIDs should be privacy-preserving, role-scoped, and protected against unnecessary public exposure. Pairwise or context-specific DIDs may be appropriate where privacy risks are high. An **organizational DID** identifies an institution, governance body, consortium, registry, credential issuer, Project SPV, public authority interface where applicable, enterprise evidence room, community steward body, academic institution, NGO, operator, or standards-mapping body. Organizational DIDs carry governance responsibility and may issue credentials, sign governance records, publish clauses, or operate nodes within scope. A **machine DID** identifies a non-human technical system: TEE node, secure enclave, confidential VM, sensor, oracle, simulation runner, AI agent, runtime, scheduler, rollup builder, registry service, model service, edge device, or data provider endpoint. Machine DIDs are essential because machines produce CACs, attestations, sensor inputs, simulation outputs, and audit events. Machine DIDs should have strong key management, attestation linkage, workload scope, and automated revocation. A **clause or artifact DID** may identify persistent governance objects such as Smart Clauses, CAC schemas, credential schemas, simulation bundles, public-safe profiles, parameter records, proof profiles, rollup schemas, or registry objects. This allows governance artifacts to be referenced, versioned, and resolved consistently. Clause identity may also use Clause IDs and hashes, but DID-based artifact resolution can support service endpoints, metadata, and governance records. A **node or network DID** may identify sovereign nodes, regional nodes, community nodes, enterprise evidence rooms, controlled-room environments, or validator sets. These DIDs support orchestration, attestation, scheduling, rollup signing, and cross-registry verification. The seed says four canonical categories but does not list them. A mature NSF profile can define at least four primary categories: human, organization, machine, and artifact. Node DIDs may be a machine subtype or its own category depending on implementation. Each DID category should have distinct issuance, key rotation, suspension, revocation, delegation, and audit rules. ### DID Format and Method NSF DIDs may use an NSF-specific DID method, such as: ``` did:nsf:: ``` Examples include: ``` did:nsf:human:0x84b1f9... did:nsf:org:0x59fe... did:nsf:machine:0x491e7c... did:nsf:artifact:0xab33... did:nsf:node:0x72f0... ``` However, NSF should remain DID-method plural where necessary. Some actors may use `did:web`, `did:key`, `did:ion`, `did:pkh`, sovereign DID methods, enterprise identity methods, national digital identity methods, or other W3C-compatible DID methods. The key requirement is not that every identity uses `did:nsf`. The requirement is that every DID used in NSF resolves to a DID Document or equivalent verifiable metadata that supports keys, service endpoints, credential compatibility, status, and governance scope. The NSF DID method, if used, should provide strong registry linkage, revocation, governance metadata, and protocol interoperability. It should not prevent recognition of external DID methods where authorized. A DID Document should include public keys, verification methods, authentication keys, assertion keys, key agreement keys, capability invocation keys, capability delegation keys, service endpoints, credential registries, audit endpoints, revocation endpoints, and metadata references. It should define key usage. A signing key for CACs should not automatically be usable for credential issuance. A credential issuer key should not automatically be usable for node attestation. A human authentication key should not automatically be usable for governance override. DID Documents must be versioned and audit-linked. Key rotation, revocation, delegation, service endpoint changes, and scope changes should leave records. The DID format gives identity an address. The DID Document gives it verifiable structure. ### Role Binding and Scope Tagging Every DID used in NSF should be role-bound and scope-tagged. A role binding states what the DID is allowed to do. A scope tag states where, when, and under which governance context that role applies. Roles may include TriggerAgent, ClausePublisher, ClauseMaintainer, SimulationValidator, ModelReviewer, PublicSafeReviewer, CredentialIssuer, CredentialHolder, TEEExecutor, RollupCoordinator, AttestationVerifier, NationalNodeOperator, RegionalNodeOperator, CommunitySteward, ProjectSPVReviewer, EvidenceRoomOperator, AIModelOperator, AI-Agent, SensorProvider, OracleProvider, RegistryMaintainer, ParameterPublisher, DataSteward, GovernanceSigner, DisputeReviewer, SafeModeOperator, and AuditPublisher. Scopes may include jurisdiction, domain, clause family, risk class, data class, authority class, SDZ, community territory, Project SPV, enterprise evidence room, public-safe profile, credential schema, simulation model, time period, and recognition boundary. A role binding may look like: ```json { "did": "did:nsf:org:0x59fe", "roles": [ { "role": "ClausePublisher", "domain": "EmissionsEvidence", "jurisdiction": "ETH", "credential_required": "ClausePublisherVC@1.0", "authority_class": "evidence-support", "valid_from": "2025-01-01", "expires": "2025-12-31" } ], "revocable_by": [ "did:nsf:org:NationalRegistryAuthority" ], "issued_credentials": [ "EmissionsOperatorEvidenceVC" ] } ``` The seed includes `UNFCCC::RegionalDAO`. This should be handled carefully. Unless there is official authorization, examples should use `UNFCCCRef`, `ClimateEvidenceRegionalGovernance`, or `EmissionsEvidenceRegionalNode`, not an official-sounding UNFCCC DAO. Role binding prevents an identity from becoming unlimited. A DID can sign only what its active credentials and scope permit. A human DID may be a simulation reviewer in Kenya for one domain but not a credential issuer in another. A machine DID may execute disaster clauses but not health clauses. An organization DID may publish reference mappings but not public authority decisions. Scope is what turns identity into bounded accountability. ### DID Registration and Governance DIDs used in NSF should be registered or recognized in an NSF-compatible DID Registry. The registry does not need to control every DID globally, but it must record which DIDs are recognized for which NSF roles, under which credentials, in which jurisdictions, and with which revocation paths. DID registration should include category, DID method, controller, linked credentials, origin evidence, jurisdiction, role bindings, service endpoints, public keys, key usage, issuer relationships, revocation method, audit obligations, privacy profile, and status. Registration should be anchored to evidence of origin. A human DID may be linked to a verified credential issued by an institution or identity provider. An organizational DID may be linked to a registry record, institutional credential, charter, or governance record. A machine DID may be linked to hardware attestation, node onboarding, sensor credential, or runtime registration. An artifact DID may be linked to a clause hash, schema record, simulation bundle, or registry entry. The seed says DIDs are approved by DAO validator quorum. Mature NSF language should say approved or recognized by the relevant registry authority, governance quorum, national node, community steward, credential issuer, enterprise evidence governance function, or validator set depending on scope. DAO voting may be an implementation option, not the universal authority model. The registry should index DIDs by type, jurisdiction, credential history, revocation status, clause interaction logs, issued credentials, consumed credentials, node activity, CAC signatures, attestation history, rollup participation, dispute status, and public-safe role. Governance rules should define onboarding, permission delegation, role escalation, expiration, suspension, revocation, recovery, and dispute. DID registration makes identity discoverable and governable. ### Origin, Delegation, and Trust Chains DID trust depends on origin and delegation. A DID should be able to show how it obtained authority. An organizational DID may delegate a specific role to a human DID. A national node DID may delegate node operation to a machine DID. A credential issuer DID may delegate signing to a controlled key. A Project SPV DID may delegate evidence review to an evidence room operator. A community governance DID may delegate public-safe review to a steward DID. An AI agent DID may be delegated limited tool access by an organizational DID. Delegation should be credential-based and scope-limited. A delegation credential should state delegator, delegate, role, scope, expiration, allowed actions, revocation path, and audit obligations. Delegation should not create broader authority than the delegator holds. Delegation chains should be short for high-risk actions. A clause should be able to resolve whether a DID’s authority is direct or delegated, whether the delegator is active, whether the delegation is still valid, whether the role applies to the clause, and whether the jurisdiction matches. Trust chains prevent anonymous keys from acting as institutions. ### Signing and Verification Workflows DIDs are used throughout NSF signing workflows. A DID may sign CACs, clause deployments, clause updates, governance decisions, credential issuances, credential status updates, node registrations, attestation statements, rollups, public-safe approvals, simulation reviews, parameter updates, fork approvals, safe-mode overrides, audit records, and dispute outcomes. Every signing action should be linked to a key in the DID Document and to a credential authorizing the action. A valid signature proves control of a key. It does not prove permission. The verifier must check both signature validity and authorization. A signing workflow should verify: The DID resolves. The key is active. The key usage permits the action. The DID status is active. The required credential exists. The credential is active and not revoked. The credential issuer is recognized. The role scope matches the action. The jurisdiction matches. The clause or artifact is within scope. The timestamp falls within validity window. The action is not blocked by safe-mode, dispute, or revocation. All signing actions should be logged in the Audit Layer. The audit record should include DID, key ID, credential reference, action type, timestamp, jurisdiction, clause or object reference, signature, verification result, and proof scope. If a key expires or is revoked, future signatures fail. Historical signatures may remain valid for the period when the key was active, unless compromise retroactively affects a window. The audit system must distinguish historical validity from current authority. Signing is the act. Verification is the governance check. ### DID-to-VC Linkage Each DID may be bound to one or more Verifiable Credentials. These credentials define what the DID can do. A DID without credentials may be known but not authorized. A DID with expired credentials may be attributable but inactive. A DID with credentials in one jurisdiction may not be recognized in another. A binding may look like: ```json { "did": "did:nsf:human:0x9f3e", "credential_ref": "DisasterOperatorVC#0x1823", "valid_from": "2025-01-01", "expires": "2025-06-30", "jurisdiction": "KEN", "roles": ["DisasterEvidenceOperator"], "allowed_actions": ["submit-field-attestation", "request-clause-execution"], "prohibited_actions": ["issue-public-warning", "approve-finance"] } ``` VCs can define operational authority, access rights, credential usage scope, signing rights, decryption rights, execution rights, threshold capabilities, cross-jurisdictional roles, training status, public-safe role, node eligibility, model reviewer status, or enterprise evidence access. They can also define limitations and prohibited claims. A DID may hold many credentials, but clauses should require specific credentials for specific actions. Having one valid credential does not imply general authority. A human may be a field operator but not a public-safe reviewer. A machine may be a TEE executor but not a rollup coordinator. An organization may be a credential issuer for one schema but not another. DID-to-VC linkage is the basis of role-based governance in NSF. ### DID Revocation, Key Rotation, and Recovery DIDs and keys must be revocable and rotatable. Compromise, role change, expiration, organizational change, hardware failure, employee departure, credential revocation, legal intervention, community decision, or governance dispute may require suspension, revocation, or rotation. Revocation can occur at several levels. A key can be revoked while the DID remains active. A credential can be revoked while the DID remains active. A role binding can be suspended. A DID can be deactivated. A machine DID can be quarantined. A node DID can be removed from scheduling. An artifact DID can be deprecated. An issuer DID can be suspended, causing credentials it issued to require review. Revocation should be anchored through credential status registries, DID registry status, sparse Merkle trees, CRLs signed by governance nodes, accumulator proofs, or other verifiable status systems. Revocation records should include reason, scope, effective time, issuer or revoker, evidence reference, appeal path, and audit record. Key rotation should preserve continuity. A DID Document may update verification methods. Historical signatures should remain verifiable against historical DID state. The Registry and Audit Layer should preserve DID Document versions. Rotation should not allow repudiation of prior actions. Recovery should be governed. Human DID recovery may require multi-factor or institutional recovery. Organizational DID recovery may require governance signers. Machine DID recovery may require re-attestation. Community DID recovery may require community process. Project SPV DID recovery may require enterprise governance. DID lifecycle management is necessary for long-term trust. ### DID Disputes and Challenges A DID or its authority can be challenged. A challenge may claim that a DID was wrongly registered, a role was misassigned, a key was compromised, a credential was invalid, a delegation exceeded scope, a signature was unauthorized, a machine DID produced false attestations, or an organizational DID misrepresented authority. The dispute process should load DID registry records, DID Document versions, credential bindings, delegation chains, signatures, CACs, audit records, revocation status, and governance scope. Outcomes may include uphold, suspend, restrict, revoke, rotate keys, require additional proof, annotate historical records, notify affected credential issuers, or escalate to competent authority. DID disputes are essential because identity infrastructure itself can fail. NSF must not assume that identity records are always correct. It must make them correctionable. ### DID-Based Authorization in Clause Logic Smart Clauses use DIDs to authorize actions. Clause logic should not ask merely whether a signer has a key. It should verify DID, credential, role, jurisdiction, scope, and status. A simplified authorization pattern may look like: ```scl if signer.did in RegistryGroup("AuthorizedReliefCoordinators") and signer.hasCredential(ReliefCoordinatorVC) and signer.credential.status == "ACTIVE" and signer.credential.recognizedIn(jurisdiction) { allow requestExecution(ResourceRoutingEvidenceClause) } ``` The seed example uses: ```scl if signer in did:nsf:org:WFP-DAO and hasVC("ReliefCoordinatorVC") { execute(ResourceTransferClause) } ``` This should be reframed to avoid implying WFP authorization, DAO identity, or resource transfer execution unless actually authorized. A safer pattern is: ```scl if signer.did in GovernanceRegistry("HumanitarianResponseEvidenceReview") and hasVC(signer, "ReliefCoordinationEvidenceRoleVC") and credential.status == "ACTIVE" and credential.jurisdiction == clause.jurisdiction { routeTo AuthorizedProgramAdministrator generateCAC boundary "evidence-support-not-resource-transfer-approval" } ``` DID-based authorization provides programmable role control, but it must preserve non-execution boundaries. A clause can authorize evidence routing, credential checks, review requests, proof generation, or technical workflow actions. It should not imply public authority, relief approval, finance release, or legal enforcement unless the competent actor and lawful framework authorize that effect. ### DID-Based Authorization for Machines and AI Agents Machine DIDs are central to NSF. A TEE node DID signs CACs. A sensor DID signs observations. A simulation runner DID signs model runs. A rollup coordinator DID signs rollups. An AI agent DID requests tool use. A scheduler DID signs job dispatch. A registry service DID signs status responses. Machine DIDs require stricter controls than ordinary service accounts. They should be bound to attestation, runtime measurement, key management, workload scope, and revocation. A TEE node DID should not sign CACs unless attestation passes. A sensor DID should not sign observations outside its calibration or jurisdiction. An AI agent DID should not access data without tool-use credentials. A rollup builder DID should not publish rollups outside scope. AI agent DIDs should include model identity, operator, tool permissions, memory policy, data access class, public-safe profile, and incident status. Agent credentials should be short-lived and dynamic. If model risk changes, agent credentials may be restricted or suspended. Machine identity makes automation accountable. ### DID-Based Encryption and Access Control DIDs also support encryption. DID Documents may include key agreement keys used to encrypt CAC fields, credential payloads, audit records, or controlled evidence. Access can be credential-gated: a user or agent presents a DID-linked credential, then receives decryption access if policy permits. For example, a CAC field may be encrypted for all DIDs holding `PublicHealthResponseAuthorityVC` in a matching jurisdiction. Or a Project SPV evidence CAC may be encrypted to specific evidence-room reviewer DIDs. Or a community-protected CAC may require threshold decryption by community steward DIDs. DID-based encryption must include key rotation and revocation. If a DID loses access, future decryption should fail. Previously decrypted data cannot be technically “undecrypted,” so access should be minimized and logged. DID-based access control links identity, credentials, and privacy. ### DID Privacy and Pairwise Identity DIDs can create privacy risks if reused too broadly. A single DID used across health, finance, migration, community, and public-safe systems can become a correlation vector. NSF should support pairwise DIDs, context-specific DIDs, pseudonymous DIDs, and selective disclosure credentials where appropriate. A human may use different DIDs for different contexts, linked only under authorized review. A community participant may use a protected DID. A whistleblower or vulnerable person may require privacy-preserving credentials. An AI agent may use task-specific DIDs. A Project SPV reviewer may use an institutional DID for official actions and a separate credentialed DID for controlled-room access. Privacy-preserving DID use must still allow accountability under proper governance. The system should support concealed public identity with controlled de-anonymization or institutional accountability where lawful and necessary. DID privacy prevents identity infrastructure from becoming surveillance infrastructure. ### DID Integration Across NSF Layers DIDs operate across every NSF layer. In the Data Layer, DIDs identify data providers, sensors, stewards, and access controllers. In the Compute Layer, DIDs identify TEE nodes, runtimes, schedulers, and proof systems. In the Governance Layer, DIDs identify governance bodies, reviewers, signers, and dispute actors. In the Credential Layer, DIDs identify issuers, holders, verifiers, subjects, and status authorities. In the Clause Layer, DIDs sign clause publication, updates, forks, and deprecations. In the Simulation Layer, DIDs identify model maintainers, simulation runners, validators, and reviewers. In the Communication Layer, DIDs authenticate messages, job tokens, triggers, and notifications. In the Audit Layer, DIDs provide attribution for every material action. In the Registry Layer, DIDs provide discoverable identity, status, and scope. This is why DIDs are not an optional identity add-on. They are the accountability spine of NSF. ### DIDs Across GNC, RNC, and NNC Architecture At the national level, National Nexus Consortiums may maintain national DID registries or recognized DID scopes for domestic nodes, reviewers, credential issuers, public-safe actors, Project SPV evidence rooms, and data providers. National DIDs preserve domestic jurisdiction and institutional control. At the regional level, Regional Nexus Consortiums may recognize national DIDs, issue regional role credentials, maintain regional verifier sets, and support mutual recognition. Regional DID governance should not override national authority. At the global level, the Global Nexus Consortium may define DID schemas, interoperability profiles, credential binding patterns, public-good DID registries for reference artifacts, and cross-registry verification tools. It should not become the universal identity authority for all actors. At the community level, community and Indigenous governance bodies may maintain steward DIDs, protected participation DIDs, community data access credentials, and public-safe review identities. Community identity rules must respect local governance and privacy. At the enterprise layer, National Consortium Companies, Project SPVs, providers, operators, insurers, investors, contractors, and evidence rooms may maintain enterprise DIDs for lawful implementation and controlled evidence workflows. These DIDs remain enterprise-scoped and do not imply public-good endorsement, finance approval, or insurance underwriting. DID governance must be federated because identity authority is plural. ### DID Boundary Statement DIDs support authentication, signing, encryption, credential issuance, credential verification, node identity, runtime attestation, clause publication, governance participation, audit attribution, AI agent control, Project SPV evidence workflows, finance-readiness evidence, insurance-readiness evidence, and cross-jurisdictional traceability. They do not by themselves create legal authority, public authority status, professional licensing, regulatory approval, certification, procurement approval, finance approval, investment advice, insurance underwriting, claims determination, official public warning status, treaty compliance, legal liability, or universal recognition. A DID proves or resolves identity and key control under a method and registry. Authority depends on credentials, issuer status, governance scope, jurisdiction, applicable law, contracts, community rules, enterprise authorization, and institutional adoption. A DID is not authority. A signature is not permission. A credential is not universal recognition. A machine DID is not proof of safe execution without attestation. An organizational DID is not public authority unless legally recognized. A finance-readiness DID role is not finance approval. An insurance-readiness DID role is not underwriting. This boundary must appear in DID registries, DID Documents, credential schemas, verifier tools, agent policies, CAC records, audit dashboards, and public documentation. ### DIDs as Trust Anchors for Global Digital Governance In NSF, every material action is linked to a DID. Every DID is linked to keys. Every key is scoped by usage. Every role is defined by credentials. Every credential is linked to issuer authority, jurisdiction, and status. Every credentialed action is recorded in the Audit Layer. Every CAC identifies the runtime, node, signer, and governance scope. Every dispute can trace who or what acted, under which identity and authority. This creates a cryptographically verifiable identity substrate for digital governance. Humans become accountable without being overexposed. Organizations become identifiable without becoming universal authorities. Machines become governable actors. AI agents become permissioned systems. Credentials become role-bound. Clauses become signer-aware. CACs become attributable. Rollups become verifier-scoped. Audit trails become identity-linked. DIDs are therefore not only technical identifiers. They are the identity grammar of NSF. They allow the framework to coordinate across humans, machines, institutions, jurisdictions, communities, and enterprise systems without collapsing trust into one platform or one authority. That is the role of Decentralized Identifiers in the Nexus Sovereignty Framework: to make every governance-relevant action attributable, credential-bound, revocable, auditable, jurisdiction-aware, privacy-preserving, and interoperable across the full public-good and enterprise execution stack. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.therisk.global/organization/standardization/nexus-sovereignty/v.-verifiable-credentials/did-format-human-org-machine-system.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.