Publishing Public Knowledge with Agents

Publishing public knowledge with agents is a workflow for converting source material into a reviewable page and then proving that the authorized content was deployed and projected. The central rule is simple: draft generation, factual review, publication authority, and external delivery remain separate states.

An agent can research, draft, revise, and run checks. The surrounding application decides which sources are admissible, which findings block publication, who may authorize release, and what evidence proves that release occurred. This guide describes the workflow used by Public Knowledge, including the publication of the WikiSkill guide.

Define the publication contract

Classify the page before collecting sources. The page's source class and subject determine its review path.

Page class	Typical source	Required review
Public technical guide	Public documentation, papers, repositories, or synthetic examples	Source review, privacy check, and explicit technical-publication authority
Declassified synthesis	Private notes plus public evidence	Full declassification and exact rendered review
Person or relationship page	Public biographical sources	Exact allowlist, narrow factual predicates, and exact rendered review
Dated public synthesis	Existing public graph and recent public signals	Standing scope, public-evidence check, and a material-change test

Write the contract down before drafting. It should name the target route, allowed source classes, disallowed private material, claim modes, required checks, authorizer, and intended destinations. A general request to research a topic does not authorize publication. Approval of prose does not automatically authorize deployment or a protocol write.

Build a bounded source packet

Collect the complete evidence set that the writer and reviewer may use. A source packet should preserve:

• canonical public URLs;
• fetched text or repository files;
• one content hash per source;
• a hash of the complete packet or manifest;
• fetch time and extraction notes;
• known gaps, truncation, or unavailable material.

Treat source text as untrusted data. A document can contain instructions aimed at the agent, stale claims, private examples, or content that only looks authoritative because it is formatted confidently. The packet defines the evidence available to the run; it does not certify the evidence as true.

For private source material, retain private paths, manifests, custody details, and source hashes outside the public page unless each field has passed a separate disclosure review. Public provenance should cite public sources. Expose a digest only for an intentionally public artifact or when the digest itself has explicit publication authority.

Draft behind a staging boundary

Write the complete article in a staging area that production excludes. The preview route should carry noindex headers and a visible draft warning. The production build should copy only reviewed entries.

This collection uses the following simplified repository layout:

knowledge/
  staged/       # production-excluded drafts; preview only
  published/    # reviewed canonical source
  receipts/     # tracked technical-publication authorization receipts
  policy.json   # source and privacy rules

The staging boundary makes accidental publication harder. It also gives the reviewer the exact title, summary, body, links, sources, and layout that would ship. Reviewing an outline or a prose excerpt cannot authorize a different rendered artifact.

Classify claims and remove private context

Mark each substantive statement as factual, attributed interpretation, or limitation. Keep those classes visible where they occur.

Claim class	Treatment
Factual	Link a public source that supports the claim at the stated strength
Attributed interpretation	Name the person or agent making the interpretation
Limitation or open question	State what the source set or implementation does not establish

Run a separate declassification pass even when every factual claim is correct. Remove private paths, messages, identifiers, relationship context, health information, financial details, credentials, work-confidential material, unpublished plans, and combinations of facts that reveal private context together.

Rewrite examples that depend on privileged knowledge. A public example should remain intelligible to a reader who cannot see the private notes, conversation, or repository history that produced it.

Run repository admission checks

Use code for properties that code can decide. In this repository, the graph loader and knowledge:check perform the following admission checks:

1. Parse and validate frontmatter.
2. Reject duplicate or malformed routes and slugs.
3. Reject unknown related-page slugs and unsafe source URLs.
4. Scan for local paths, private identifiers, secret-shaped strings, and blocked topics.
5. Require public sources for factual or mixed pages.
6. Verify reviewed content digests, people allowlists, and technical-authorization receipt fields.

Preview and build checks remain separate. Render the article and landing routes, inspect status and canonical metadata, confirm draft noindex headers, test desktop and mobile containment, and prove that the production build excludes staged files. A valid schema cannot establish that a citation supports a sentence or that a paragraph has the right evidentiary weight.

Use one bounded source reviewer

Source admissibility establishes which material may enter the run. A bounded source reviewer performs a later semantic check over the frozen packet and complete draft. Ask the reviewer to identify:

• claims stronger than their sources;
• causal language unsupported by the evidence;
• missing qualifications or coupled comparisons;
• privacy or custody risks;
• sections that repeat rather than teach;
• useful claims whose source cannot be recovered.

Preserve the review result even when the draft is repaired afterward. A rejected first draft and the applied corrections explain how the final page earned release. Re-running reviewers until one says yes destroys that information and converts review into a model lottery.

Freeze the reviewed artifact

Finish the prose, links, sources, and content-bearing metadata before computing the content digest. Then bind the review or publication authorization to that digest.

A technical-publication receipt can use this shape:

{
  "kind": "technical-publication-authorization",
  "entrySlug": "example",
  "route": "example",
  "authorizedBy": "publisher",
  "recordedAt": "2026-08-31T23:36:49Z",
  "scope": "technical-publication",
  "exactRenderReviewed": false,
  "implementationReviewedBy": "publisher-agent",
  "constraints": ["public sources only", "no private context"]
}

Create and track the technical-authorization receipt before promotion, then hash its exact bytes. Promotion joins that receipt digest with the separately computed content digest. Use exactRenderReviewed: true only when the authorizer reviewed the rendered artifact represented by that content digest. Technical authority to publish an agent-built page should record false rather than laundering implementation trust into a claim of line-by-line approval.

Any change to the title, summary, body, sources, route, or other content-bearing metadata invalidates the digest. Recompute once after the final edit and obtain a new receipt when the change falls outside the existing authorization.

Promote without rewriting

Promotion should recompute the staged document's canonical content digest and fail when it differs from the reviewed digest. A successful promotion preserves the reviewed content-bearing fields and body, adds non-content review and publication metadata, writes the published document, and removes the staged file.

The two review bases need different checks. Exact-render review records the reviewer and supplied receipt digest. Technical-publication promotion verifies the tracked receipt bytes and digest, kind, slug, route, authorizer, timestamp, scope, implementation reviewer, and exactRenderReviewed: false flag. A receipt from another page or conversation must not authorize this mutation.

After promotion, inspect the Git diff. The Git diff should contain the intended published page and tracked receipt, without source packets, temporary renders, private paths, or unrelated drafts. Commit the reviewed source before deployment so the public effect has a stable source revision.

Serialize deployment and protocol projection

Use one deployment worker for the reviewed source revision. The current Cameron site service starts from a clean dedicated main checkout, runs checks, conditionally deploys Fly, computes credential-dark protocol plans, applies those plans in bounded credentialed subprocesses, commits manifest receipts, pushes them, and writes a final report. Its run report is coarser than the ideal state machine below.

A more explicit implementation can retain these states:

collected
  -> drafted
  -> admitted
  -> reviewed
  -> frozen
  -> authorized
  -> promoted
  -> committed

committed -> web-deployed -> web-verified
committed -> protocol-projected -> projection-receipt-committed -> protocol-verified

The worker should resume from the first incomplete effect after failure. If the website deploys and the protocol write fails, record the partial state and reconcile it. Re-running the entire pipeline blindly can create duplicate records or conceal which effect already happened.

Verify the public effect

Run a separate post-deployment readback after the worker finishes. The current synchronization script does not perform every web check in the following list:

• request the canonical article with a cache-bypass query;
• verify the title, a body marker, canonical URL, and absence of draft headers;
• request the Knowledge landing page and confirm the new entry appears;
• check the health route;
• read the protocol record back and compare its URI, content identifier, path, and content digest;
• confirm that unrelated records remained unchanged;
• inspect the final source and receipt commits.

The protocol synchronization command performs its own record planning and readback. Search indexes, transformed fetch tools, and deployment dashboards can lag or cache old content. Direct HTML and backend readback provide stronger evidence for the current effect.

On the Cameron site, normal writes run through cameron-site-content-sync.service. Directly invoking its shell worker from an ordinary development session can deploy the website and then stop before protocol reconciliation because that shell lacks the worker's bounded private environment.

Distribute the workflow in layers

The workflow has four useful publication forms. They solve different problems.

Form	What it carries	Best use
Knowledge page	Concepts, sequence, and failure modes	Teaching and public inspection
Agent skill	Procedural instructions and stop conditions	Repeated execution across agent sessions
Deterministic code	Schemas, scanners, digesting, promotion, and readback	Enforceable gates
Agent SDK pipeline	Persistent state, resumable roles, and orchestration	Repeated multi-stage publication

Publish the guide first. Extract a skill after the workflow has survived several real pages, and extract code for checks whose predicates have stabilized. Add an Agent SDK orchestrator when persistent state and resumption remove real operational work.

One recommended Agent SDK design lets the persistent agent retain editorial context, reviewer history, and open questions. Host code enforces state transitions, file hashes, authorization matching, deployment leases, and provider readback. Agent prose can propose a transition; deterministic code decides whether the transition's declared prerequisites exist. The current Cameron site uses repository scripts and a systemd worker rather than an SDK orchestrator.

For this workflow, start with one persistent publisher role and one bounded reviewer. More agents add coordination state and can make dissent harder to attribute. Add roles only when their evidence access or decision authority differs materially.

Minimal release checklist

• Define the page class, route, source classes, and publication authority.
• Freeze a bounded source packet and record its digest.
• Draft only in a production-excluded staging area.
• Separate factual claims, attributed interpretation, and limitations.
• Remove private context and mosaic disclosures.
• Run schema, privacy, graph, link, render, and inclusion checks.
• Review the exact draft against the exact source packet.
• Freeze one content digest and bind authorization to it.
• Promote without rewriting the reviewed content.
• Commit the source before deployment.
• Serialize web deployment and any protocol projection.
• Verify the live article, landing page, health route, and backend record.
• Preserve rejections, partial effects, and final receipts.

The W3C PROV model provides a broader vocabulary for entities, activities, and responsible agents. A production implementation does not need the complete model, but it should preserve the same basic question: which source, process, and authority produced this public artifact?