Go
The Go module reads, checks and resolves instruction.md documents, verifies their signatures, and follows a released instruction over MCP from your own agent. It is package instruction, version 0.1.0, with a command-line tool, instruction-md.
The module does two jobs. Working with documents runs offline: read a document into its tree with the reader's diagnostics, check it, resolve it with its bases and includes, produce the text an agent receives, format it, digest it and verify its signatures. Following talks to an instruction.md MCP server: a Follower reads an instruction, checks it against your policy, applies it, keeps the last good version when a new one fails a check, and reports which version it applied. HTTPClient speaks MCP 2026-07-28 with the standard library only.
It is a port of the TypeScript reference, the npm package instruction.md (JavaScript and TypeScript). Its tests run the specification's conformance cases and the reference's vectors, and agree with them byte for byte.
| Module | github.com/instruction-md/source-code/sdks/go, package instruction |
| Version | 0.1.0, pre-1.0, no tagged release yet |
| Go | 1.22 or later, on any platform Go supports |
| Dependencies | The standard library and gopkg.in/yaml.v3 |
| Specification | First edition, instruction/1 (spec: "1") |
| MCP | 2026-07-28, stateless: no initialize, no session |
| Signatures | Ed25519 JWS (EdDSA) through crypto/ed25519 |
| Licence | Business Source License 1.1, source-available; each version becomes Apache 2.0 four years after it is published |
| Not included | Sealed instructions, and the write tools (creating, editing, releasing). Use the CLI or the editor for those. |
Install
Import the package:
import "github.com/instruction-md/source-code/sdks/go/instruction" Then add the requirement and the replace, and tidy:
# in your module, once a .go file imports the package
go mod edit -require=github.com/instruction-md/source-code/sdks/go@v0.0.0 \
-replace=github.com/instruction-md/source-code/sdks/go=<path to sdks/go>
go mod tidy Run go mod tidy only after a file imports the package. In a module that imports nothing from it yet, tidy drops the requirement you just added, and the next build fails with "is replaced but not required".
The command-line tool builds from the module's directory:
# from the module's directory
go run ./cmd/instruction-md check FILE # run it in place
go install ./cmd/instruction-md # or put instruction-md on your GOBIN Read, check and deliver a document
Save this as main.go in a new module, point the module at the source as above, and run go run .:
package main
import (
"fmt"
"github.com/instruction-md/source-code/sdks/go/instruction"
)
const text = `---
spec: "1"
title: House style
parameters:
audience: { type: string, default: developers }
---
# House style
You write for ${audience}.
MUST: write in the second person.
BECAUSE: the reader is the one acting.
NEVER: promise a date you cannot keep.
`
func main() {
r := instruction.Read(text, instruction.ReadOptions{}) // r.Document: {format, metadata: {front, back}, body}
fmt.Println(r.Document.Format) // instruction/1
fmt.Println(len(instruction.CheckReading(r))) // 0: the reader's diagnostics and the inline checks
res := instruction.Resolve(text, instruction.ResolveOptions{
URI: "house-style.md",
Params: map[string]any{"audience": "support engineers"},
// a base or an include, by resolved URI; nil: absent (this document composes nothing)
Load: func(uri string) *instruction.Source { return nil },
})
fmt.Println(res.OK) // true: a resolution a registry may deliver
fmt.Print(res.Text) // what the agent receives (instruction-text/1)
fmt.Println(instruction.Digest(text))
} It prints:
instruction/1
0
true
# House style
You write for support engineers.
MUST: write in the second person.
BECAUSE: the reader is the one acting.
NEVER: promise a date you cannot keep.
sha256:20f4f08abec3d38ca9b2324884e1063fd1b0eb1751da2a5c08b29945b775ae84 res.Resolved is the resolved artifact (instruction-resolved/1); its ResolvedDigest is the sha256 of its RFC 8785 form. r.Text(params) is the agent text of the document on its own, without resolving anything.
Check returns every diagnostic in source order: the reader's, the inline checks' and the workflow checks'. Each has a stable Code, a Severity (error, warning or info), a Message and usually a line Range. Use the Code in your logic: messages may be reworded.
const text = `---
spec: "1"
title: Refunds
---
Ask :person[the owner]{ref=#owner} before a refund over ${limit}.
:::policy{id=refunds
MUST: refund within 14 days.
`
for _, d := range instruction.Check(text, instruction.ReadOptions{URI: "refunds.md"}) {
line := 0
if d.Range != nil {
line = d.Range.Start
}
fmt.Printf("%s line %d %s: %s\n", d.Severity, line, d.Code, d.Message)
} warning line 6 parameter-optional: ${limit} is not a declared parameter, so it stays as written
warning line 6 reference-optional: :person[…]: nothing in this document has the id "owner"
error line 8 invalid-attributes: :::policy: its attribute list must close with } at the end of the line
error line 8 unclosed-directive: :::policy is not closed: end it with a line of ::: Treat any instruction.Error as a document a registry won't deliver. The codes are listed in Diagnostics.
Resolve a document that extends another
Resolve loads each base and include through your Load function. ResolveWith takes sources you already loaded, keyed by resolved URI. Relative references resolve against ResolveOptions.URI.
const base = `---
spec: "1"
title: Support baseline
---
:::policy{id=tone title="Tone"}
SHOULD: answer in under 120 words.
:::
`
const agent = `---
spec: "1"
title: Support agent
extends:
- { uri: ./base.md, as: baseline }
---
# Support agent
:::replace{target="#baseline/tone" reason="Customers read replies on a phone."}
SHOULD: answer in under 80 words.
:::
MUST: link the help page you used.
`
res := instruction.ResolveWith(agent, map[string]*instruction.Source{
"https://example.org/support/base.md": {URI: "https://example.org/support/base.md", Text: base},
}, instruction.ResolveOptions{URI: "https://example.org/support/agent.md"})
fmt.Println(res.OK, res.Resolved.Status) // true complete
for _, dep := range res.Resolved.Dependencies {
fmt.Println(dep.ResolvedURI, dep.Mode, dep.Instance) // https://example.org/support/base.md live root/baseline
}
fmt.Print(res.Text) ### Policy: Tone
SHOULD: answer in under 80 words.
# Support agent
MUST: link the help page you used.
### Composition changes
- replace baseline/tone (origin: https://example.org/support/agent.md) — Customers read replies on a phone. A source your loader can't find is nil. A required one makes the resolution fail (res.OK is false, with an error diagnostic); an optional one leaves it partial. Composition is bounded by MaxDepth (default 8) and MaxSources (default 64): past either is an error, never a shortened result. See Composition.
Verify a signature
A released version carries an author signature over its exact bytes, and the registry can sign what it delivered to one reader. VerifyAuthor and VerifyDelivery check them against Ed25519 public keys (JWKs).
text := "---\nspec: \"1\"\n---\n\nMUST: cite the policy you used.\n"
pub, priv, _ := ed25519.GenerateKey(nil)
jws, _ := instruction.SignJWS(map[string]any{ // for this example; in production the publisher signs
"spec": "instruction/1",
"typ": "author",
"digest": instruction.Digest(text),
"doc": "instruction://acme/refunds",
"pub": "https://instruction.md/pub/acme",
}, priv, "author")
keys := []instruction.JWK{instruction.PublicJWK(pub, "acme-2026")}
ok := instruction.VerifyAuthor(jws, text, keys, instruction.VerifyOptions{Doc: "instruction://acme/refunds"})
fmt.Println(ok.OK, ok.Claims["pub"]) // true https://instruction.md/pub/acme
bad := instruction.VerifyAuthor(jws, text+"MAY: skip it.\n", keys, instruction.VerifyOptions{})
fmt.Println(bad.OK, bad.Reason) // false author: digest does not match the authored bytes A served text may carry the host's host-integrations block, which the author never signed. Both verifiers accept the text with or without it (AuthoredCandidates). Signing and verification explains how publishers sign and where their keys are published.
Watch an instruction
Plans On Pro, Team, and Enterprise
An agent signs in with an agent credential (API key) of its own. An owner or an admin creates it in Developer ▸ API keys, or with instruction agents create NAME --org ORG after instruction login --admin. That gives a client id, a secret and a token URL, shown once. Agent credentials has the steps. Agents sign in on their own realm, so pass its token endpoint.
package main
import (
"context"
"log"
"os"
"os/signal"
"github.com/instruction-md/source-code/sdks/go/instruction"
)
func main() {
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt)
defer stop()
c := instruction.NewHTTPClient("https://instruction.md/mcp", "")
defer c.Close()
c.Tokens = &instruction.ClientCredentials{
TokenURL: "https://instruction.md/auth/realms/instruction-md-agents/protocol/openid-connect/token",
ClientID: os.Getenv("INSTRUCTION_MD_CLIENT_ID"),
ClientSecret: os.Getenv("INSTRUCTION_MD_CLIENT_SECRET"),
}
f := instruction.NewFollower(instruction.FollowerOptions{
Client: c,
URI: "instruction://acme/support-agent@stable",
Policy: instruction.FollowPolicy{RequireSignature: true, RequireDeliverySignature: true},
Report: &instruction.Report{Consumer: map[string]any{"label": "support-bot", "kind": "agent"}},
OnApply: func(a instruction.AppliedInstruction, _ *instruction.AppliedInstruction) {
log.Printf("applied v%d (%s)", a.Revision, a.VersionID) // use a.Text as the agent's instructions
},
OnHold: func(reason string, _ *instruction.AppliedInstruction) { log.Printf("held: %s", reason) },
})
c.OnUpdated = func(uri string) { f.Notify(ctx, uri) } // a release pushes a re-read
if err := f.Start(ctx); err != nil {
log.Fatal(err)
}
<-ctx.Done()
f.Stop()
} What happens:
Startreads the instruction, checks it againstPolicy, and applies it (OnApply) or holds it (OnHold).- With
Reportset, it declares a binding (instructions_bindings_create) and reports the version it applied (instructions_bindings_report). The instruction's maintainers see the agent among its followers. - Unless the URI pins a version, it subscribes (
subscriptions/listen) and re-reads everyFreshness(default 60 seconds). A release that moves@stablesends a notification, and the follower reads the new version. - A version that fails a check is held. The follower keeps the last good one in
f.Current. Losing the server means no updates, never no instructions.
Follow @stable in production: it is a ref you move on purpose. stable is never created for you: create it with instruction refs <id> set stable <version id> before anything follows it. @latest moves on every release. A pinned version (@ver_…, @v3, @3, or Mode: "pinned") never moves. An author signature names the instruction by its id (instruction://ins_…). The follower checks it against the read's canonical address, which is that id, so an owner/name URI verifies too. How following works covers refs and pinning.
Live updates are limited per workspace by plan; reads are never limited. Keep Freshness above zero and a follower without live updates still picks up a release on its next poll. Each plan's number of followers with live updates:
Plans Community 1 · Pro unlimited · Team unlimited · Enterprise unlimited
On the wire
Each request is a JSON-RPC POST carrying the mcp-protocol-version and mcp-method headers, and mcp-name (the resource URI or the tool name) on a read or a tool call, with the protocol version, client info and capabilities in params._meta. There is no initialize and no session. Answers may be JSON or a server-sent event stream. A call times out after 60 seconds.
A subscription reconnects after 1 second, doubling to 30 seconds. After it reconnects, OnUpdated is called for its URI, so a change missed in the gap is read. A 400, 403 or 404 ends the subscription. Any other failure, including a 401 with a static Token, is retried with that backoff. With Tokens set, a 401 first fetches a new token and tries once more.
ClientCredentials keeps a token until 30 seconds before it expires (300 seconds when the endpoint doesn't say) and fetches a new one after a 401. Agent tokens last five minutes, so use it, not a static token, for anything long-running.
Test with your own client
Follower needs only the three methods of the Client interface. Use any MCP client, or a fake in tests:
// memory serves one version from memory, as a registry's resources/read would.
type memory struct{ version, text string }
func (m *memory) ReadResource(_ context.Context, uri string) (*instruction.ReadResult, error) {
return &instruction.ReadResult{Contents: []instruction.ResourceContent{{
URI: uri,
Text: &m.text,
Meta: map[string]any{instruction.Meta + "versionId": m.version, instruction.Meta + "number": float64(1)},
}}}, nil
}
func (m *memory) CallTool(context.Context, string, map[string]any) (*instruction.ToolResult, error) {
return &instruction.ToolResult{}, nil
}
func (m *memory) SubscribeResource(context.Context, string) error { return nil }
func main() {
c := &memory{version: "ver_01JZ0000000000000000000001", text: "MUST: answer in English.\n"}
f := instruction.NewFollower(instruction.FollowerOptions{
Client: c, URI: "instruction://acme/support-agent@stable", Freshness: -1,
Policy: instruction.FollowPolicy{RequireSignature: true},
OnHold: func(reason string, _ *instruction.AppliedInstruction) { fmt.Println("held:", reason) },
})
_ = f.Start(context.Background()) // held: version ver_01JZ0000000000000000000001 is unsigned
fmt.Println(f.Current == nil) // true: nothing unverified was applied
} Without RequireSignature, the same follower applies the version and OnApply receives its text.
The instruction-md command
instruction-md runs the document operations from a shell or a CI step, and follows an instruction. Flags go after FILE or URI.
instruction-md check agent.md # diagnostics on stderr; exit 1 on an error
instruction-md tree agent.md # the authored tree as JSON
instruction-md deliver agent.md --param limit=200 # the agent text, bases and includes read from files beside it
instruction-md deliver agent.md --resolved # the resolved artifact as JSON
instruction-md format agent.md # the formatted document on stdout | Command | What it does | Exit |
|---|---|---|
check FILE |
Prints the diagnostics to stderr. | 1 on an error, else 0 |
tree FILE |
Prints the authored tree as JSON. | 1 on an error, else 0 |
deliver FILE |
Prints the agent text. Bases and includes are read from files under the document's directory, never above it and never from a URL. --param NAME=VALUE (repeatable) is read as the document declares NAME. --resolved prints the resolved artifact instead. Warnings go to stderr. |
1 when the resolution fails, else 0 |
format FILE |
Prints the formatted document. | 0 |
watch URI |
Follows an instruction. | See below |
A missing file, a bad --param or a usage error exits 2.
watch
export INSTRUCTION_MD_CLIENT_ID=<client id>
export INSTRUCTION_MD_TOKEN_URL=https://instruction.md/auth/realms/instruction-md-agents/protocol/openid-connect/token
export INSTRUCTION_MD_CLIENT_SECRET=<client secret>
instruction-md watch instruction://acme/support-agent@stable --require-signature --out AGENTS.md # once, in CI: exit 0 when applied, 6 when held
instruction-md watch instruction://acme/support-agent@stable --once --require-signature Each version applied is a JSON line on stdout. Each hold or error is a JSON line on stderr:
{"event":"applied","uri":"instruction://acme/support-agent@stable","versionId":"ver_01JDB6Q3W8X2K5N7P9R1T3V5X7","number":4,"verified":true,"digest":"sha256:<hex>"}
{"event":"held","reason":"version ver_01JDB7A2C4E6G8J0L2N4Q6S8U0 is unsigned"}
{"event":"error","message":"authentication required (-32000)"} | Flag | Default | Meaning |
|---|---|---|
--url | $INSTRUCTION_MD_URL, else https://instruction.md/mcp | The MCP server. |
--token | $INSTRUCTION_MD_TOKEN | A bearer token, used as is. It isn't renewed. |
--client-id | $INSTRUCTION_MD_CLIENT_ID | Sign in as this agent credential, with its secret from INSTRUCTION_MD_CLIENT_SECRET (required). The token is renewed as it expires. |
--token-url | $INSTRUCTION_MD_TOKEN_URL | The agent's token endpoint, required with --client-id. For instruction.md: https://instruction.md/auth/realms/instruction-md-agents/protocol/openid-connect/token. |
--once | off | Read once, apply or hold, report, and exit. Nothing is listened for. |
--require-signature | off | Hold a version without a valid author signature. |
--require-delivery-signature | off | Hold a version the registry didn't sign for this reader. |
--out | none | Write each applied version's text to this file (mode 0644). |
--label | instruction-md-go | The binding's consumer name, shown to the instruction's maintainers. |
--no-report | off | Declare no binding and report nothing. |
--freshness | 60s | Time between re-reads, as a Go duration (30s, 5m). 0 means notifications only. |
| Exit | When |
|---|---|
| 0 | Interrupted; with --once, a version was applied. |
| 1 | Start returned an error. In 0.1.0 it never does: a failed read is a hold, so look for 6. |
| 2 | A usage error, or --client-id without INSTRUCTION_MD_CLIENT_SECRET or --token-url. |
| 6 | With --once, the version was held. A failed read counts as held. |
watch reports itself as a consumer of kind agent. The library itself reads no environment variables; only the command reads INSTRUCTION_MD_URL, INSTRUCTION_MD_TOKEN, INSTRUCTION_MD_CLIENT_ID, INSTRUCTION_MD_TOKEN_URL and INSTRUCTION_MD_CLIENT_SECRET.
API
Everything is exported from package instruction. go doc on the module shows each item.
Reading and checking
| Name | What it is |
|---|---|
Read(text string, opts ReadOptions) *Reading |
Reads a document: the authored tree, the reader's diagnostics, and what it learned on the way. |
ReadOptions{Fragment bool; URI string; Host *PolicyLayer} |
Fragment: a part of a document. Host: a host's integrations layer, used when the front matter has none. |
Reading |
Document, Diagnostics, Identities, Parameters, Footnotes, Prose, Keywords, Reasons, Comments, Lines, FrontRange, BackRange, Policy. Methods: Identity(id), Parameter(name), Text(params). |
Check(text, opts), CheckReading(r) |
The reader's diagnostics plus the inline and workflow checks, in source order. |
InlineDiagnostics(r), WorkflowsDiagnostics(r) |
The inline checks alone; each workflow body's diagnostics alone. |
ResolveTarget(r, kind, ref) Target |
Where a typed reference points: State is local, missing or external. |
Diagnostic |
Code, Severity, Message, and optional URI, Range, Target, Remedy. Error, Warning, Info are the severities. |
ValueFrom, ValueFits, StripComments |
A parameter value from text and against its type; comments on one line. |
InlineTokens, InlineToken, SplitWiki |
The inline forms, with byte offsets. |
ClassifyLines(r) []LineInfo |
Each line's class, for editors and highlighters. |
The tree
TreeFormat ("instruction/1"), Document{Format, URI, Metadata, Body} with MarshalJSON and UnmarshalJSON, Metadata{Front, Back}, Node (Type, Kind, Form, Attrs, Children, Value, Source, Range, Instance), Attrs, StructuredValue, Range, Identity and Parameter.
Resolution and the agent text
| Name | What it is |
|---|---|
Resolve(text, opts ResolveOptions) *Resolution |
Reads the document and loads what it composes through opts.Load, each source once. |
ResolveWith(text, sources, opts), ResolveTree(doc, sources, opts) |
The same over sources already loaded, or over trees. |
ResolveOptions |
URI (default document.md), Version, Params, Load, MaxDepth (default 8), MaxSources (default 64). |
Source{URI, Text, Version}, Loader |
A source your code hands the resolver; return nil when it is absent or not readable. |
Resolution |
OK, Resolved, Text (instruction-text/1), Diagnostics, Root. |
Resolved |
The instruction-resolved/1 artifact: Status (complete or partial), Document, Body, Dependencies, Provenance, ResolvedDigest and the rest. |
ReferencesOf, ResolveURI, Slug, ToText, ValueText |
The sources a document composes; RFC 3986 resolution; a heading's anchor; the text profile of a tree. |
Format(text) string |
The conservative formatter: LF line endings, one final newline, no trailing whitespace on a directive's own lines. |
Digests and signatures
| Name | What it is |
|---|---|
Digest, DigestText, SHA256Hex, CanonicalJSON, JSONDigest |
sha256:<hex> of the exact bytes; RFC 8785 canonical JSON and its digest. |
VerifyAuthor(jws, authoredText, keys, VerifyOptions{Doc, Pub, Now}) |
Checks an author signature. |
VerifyDelivery(jws, deliveredText, deliveryKeys, authorKeys, DeliveryVerifyOptions{Aud, AuthoredText, Pub, Now}) |
Checks a delivery signature, then the author signature it embeds. Aud is required. |
VerifyResult{OK, Claims, Reason}, JWK |
The outcome; an Ed25519 key. |
SignJWS, PublicJWK |
Signing and key export, for tests and tooling. |
Following
| Name | What it is |
|---|---|
Client |
ReadResource, CallTool, SubscribeResource. |
NewFollower(FollowerOptions) *Follower |
Builds a follower; call Start(ctx). Also Refresh(ctx, reason), Notify(ctx, uri), Stop(), Pinned(). State: Current, Revision, LastHold. |
AppliedInstruction |
URI, Canonical, VersionID, Revision (the version number), Ref, Digest, DeliveredDigest, Publisher, Signature, DeliverySignature, Verified, Text, AppliedAt, and the key fields. |
NewHTTPClient(url, token) *HTTPClient |
An MCP client. Fields: URL, Token, Tokens TokenSource, ClientName (default instruction-md-go), ClientVersion, HTTP, OnUpdated. Close() ends every subscription. |
ClientCredentials{TokenURL, ClientID, ClientSecret, Scope, HTTP} |
The OAuth client-credentials grant, as a TokenSource. |
RPCError{Status, Code, Message, Data} |
A JSON-RPC error, or an HTTP failure with no answer. |
ProtocolVersion, Version, Meta, DeliveryKeysURI |
"2026-07-28"; "0.1.0"; "md.instruction/"; "instruction://delivery-keys.json". |
FollowerOptions:
| Field | Default | Meaning |
|---|---|---|
Client |
required | The MCP client. |
URI |
required | instruction://owner/name or instruction://ins_…, optionally with @ref, @vN or @ver_…. |
Mode |
"follow" |
"pinned": never move after the first apply. |
Policy |
apply anything readable | What to refuse (below). |
Freshness |
0 means 60 seconds | Periodic re-read; negative: none. |
Report |
nil: no binding, no reports | Report{Consumer, Client, BindingID}. Consumer keys: label, kind (agent, host, ci), workload. |
OnApply, OnHold, OnError |
nil | Called with each version applied, each version held, each failed read. |
Now |
UTC now, RFC 3339 | Sets AppliedAt. |
FollowPolicy, checked in this order. A version that fails is held, never applied:
| Field | Holds a version when |
|---|---|
MaxBytes |
it is larger (0: no limit). |
AllowedPublishers |
its publisher isn't listed (nil: any). |
| (always) | the registry marks it revoked. |
Publisher |
its publisher isn't this one; also pins pub in verification. |
RequireDeliverySignature |
it has no valid delivery signature for this reader. Keys from DeliveryKeys, else the registry's delivery keys. |
RequireSignature |
it has no valid author signature, or is signed with a revoked key. Keys from AuthorKeys, else the publisher's keys.json, cached for at least a minute. |
Policy, the registry and workflows
- The integrations policy:
PolicyLayer,ServerTools,Policy(ToolBlocked,TargetsAllowed),ServerPolicy,LayerOf,MergePolicy,NormalizeTarget,RemoteTargets,ToolsNamed,HostBlock,WithHostBlock,AuthoredCandidates,HostPolicyKey,AuthorPolicyKey,IntegratedKinds. See Tools and integrations. - The embedded registry:
Kinds,Common,Inline,Keywords,KeywordFlags,Rules,TypedReferences,FrontMatterKeys, the grammar's patterns,CanonicalKind,AttrSpecFor,InlineAttrSpec,ParseAttributes,AllowancePeriods. - Workflows:
WorkflowDialect,WorkflowKinds,WorkflowCommonFields,WorkflowLimit,WorkflowScopes,WorkflowDiagnostics. See Workflow node reference.
Security
- Offline by default. Reading, checking, resolving, formatting, digesting and verifying never use the network.
Resolveloads only what yourLoadreturns. - What the follower sends. Only to the MCP server you configure:
resources/readfor the instruction and for key sets; withReport, a binding and each version applied. WithRequireDeliverySignature, alsosession_bootstrap(to learn the audience the server signs for) andinstructions_versions_read. It never sends instruction content anywhere. - Credentials. A bearer token goes only to
HTTPClient.URL; the client id and secret only toTokenURL. Nothing is stored on disk. - Signatures. Turn on
RequireSignatureandRequireDeliverySignaturein production, and pin aPublisherorAuthorKeys. Without them the follower applies any version the server serves you.
Report a vulnerability through Support, not a public issue.
If it doesn't work
| What you see | What to do |
|---|---|
go get fails with "repository not found" or asks for credentials |
The module isn't public yet. Use a local copy with replace, as in Install. |
| "is replaced but not required" | go mod tidy ran before a file imported the package. Import it, then add the requirement again. |
{"event":"held","reason":"read failed (start): authentication required (-32000)"} |
The server needs a credential. Pass --token, or --client-id and --token-url with INSTRUCTION_MD_CLIENT_SECRET set. With --once the exit is 6. |
--client-id needs INSTRUCTION_MD_CLIENT_SECRET and --token-url (or INSTRUCTION_MD_TOKEN_URL) |
Set both. The secret is read only from the environment. |
the token endpoint refused the client (HTTP 401) |
The client id or secret is wrong, or TokenURL isn't the agents' realm. Agents don't sign in on the people's realm. |
| Held with "no publisher keys to verify …" | The read named no key set. Pass AuthorKeys. |
| Held with "delivery signature rejected: delivery: aud … is not this reader" | The delivery was signed for another principal. Use the agent's own credential, not a shared token. |
| A second agent gets no live updates | The workspace's plan allows fewer followers with live updates. Keep Freshness above zero; see Live updates. |
Related
- Libraries and SDKs: every library and what each does.
- How following works: refs, pinning and the follow file.
- Agent credentials: the client id, secret and token URL.
- Signing and verification: author and delivery signatures and keys.
- Sign-in, scopes and tokens: how the MCP server checks a token.
- The instruction.md Specification: the language this module reads.