Skip to content
reflow reflow docs

Edit application knowledge

The shared knowledge base describes your application at a selected revision. It is separate from executable tests. During onboarding, choose Keep tests in Reflow for a PoC without repository files, or Keep tests in the repository to version tests with your application. get_reflow_context and load_skill return guidance for that choice. Test storage explains the preference, existing test locations and explicit transfers.

In knowledge-base mode, edit shared knowledge directly. Do not maintain another corpus in the checkout or in a private folder. Local files are temporary editing or import inputs; the published shared revision remains the source of truth. In Git mode, committed corpus publication is available when you explicitly choose it; choosing Git test storage does not require a second corpus.

Edit a page without copying its body through the model

Section titled “Edit a page without copying its body through the model”

On the installed local MCP, inspect manage_knowledge_uploads with action: "root" and app. Use action: "revision" with the selected revision_id to inspect its complete document inventory. Pin that revision while editing.

{
  "action": "prepare_edit",
  "app": "my-app",
  "path": "local-development.md",
  "revision_id": "<selected-published-revision-id>"
}

The tool downloads and verifies the exact original, then returns an absolute file_path, its initial content_hash and byte count. It does not return the whole page in the tool response. Edit that temporary file with your agent’s file tools. To start a new page, omit revision_id; the file starts empty.

Upload the edited file:

{
  "action": "upload",
  "app": "my-app",
  "file_path": "<absolute-file_path-returned-by-prepare_edit>"
}

The file is private and scoped to the connected team, deployment and application. Switching any of those refuses the upload; reconnect to its original scope or start an intentional new edit. Files must be regular, exact UTF-8 and at most 256 KiB. BOM and CRLF bytes are preserved. Symlinks, hardlinks and files that change during the read are refused for temporary edits. Arbitrary profile files and home directories are not upload roots. Keep edited files owner-only (0600). An editor may replace the file’s inode (for example, an atomic save or perl -pi) before upload. Keep the same returned path and a private regular file; replacement or other changes while the upload is reading the file are refused. If an editor replaces the file with broader permissions, restore them with chmod 600 <file_path> before uploading.

file_path can also import an existing file read-only from the application’s checkout selected at MCP startup (REFLOW_LOCAL_REPO, or the detected checkout). Do not create repository files merely to use that import path in knowledge-base mode. An upload accepts exactly one of content and file_path.

For several pages, use prepare_edit with paths: ["a.md", "b.md"] and the same optional pinned revision_id. Omit the revision for a batch of new pages. Then upload accepts file_paths: ["<returned-path-a>", "<returned-path-b>"]. Do not mix batch fields with path, file_path, content or single-file IDs. Each batch accepts 1 to 25 distinct paths, processes at most two at a time, and has a single 30-second budget covering initial scope discovery and per-file work. Inspect every entry in results: preparation/upload outcomes and upload/operation IDs remain per file. The batch is not atomic. Keep accepted IDs; reconcile uncertain entries with their same IDs using the single-file actions. Entries marked not_started were not forwarded and may be submitted separately. Never replay an entire batch automatically after uncertainty.

Publish a complete candidate

Section titled “Publish a complete candidate”

Preparing or uploading a file does not publish knowledge, change the application root or approve expectations. Unpublished temporary edits are retained. Reconciling an exact publication receipt and its complete manifest attempts to remove temporary files whose current bytes have a published hash. Changed or unpublished files remain. Cleanup is best-effort and never changes the publication outcome; no age limit discards unfinished work. These files are not an automatically synchronized local corpus. This includes unedited copies and edited files just published. Call prepare_edit again after publication before making a later edit; an earlier temporary path may have been reclaimed. To abandon your own temporary edit, confirm it is no longer needed and delete that local file with your file tools. This does not delete a remote reservation or published revision. Do not automatically discard recovered or retained copies.

Retain the returned upload_id and operation_id. If upload is unconfirmed, explicitly retry the same IDs, application and exact bytes to reconcile the reservation. verify checks already transferred bytes; an incomplete rejection means resume upload first. Inspect rejection codes. To abandon an unused remote reservation, use delete with its upload ID and a fresh operation ID; published references cannot be deleted.

Publish from the pinned base with base_revision_id. Supply a format-1 manifest containing only changed or new paths, their exact hashes and byte counts, plus verified uploads for those changed hashes. Unchanged pages carry forward from that immutable revision without preparing or uploading them again. Use remove_paths to omit named base pages from the new revision; retained history is never deleted. Omission never removes a page in this mode. A path cannot be both removed and changed. base_revision_id and remove_paths are accepted only for publish; they are rejected on other actions. These removals affect the new candidate only, never retained history.

For example, if the base has nine pages and you edit only billing.md and local-development.md, prepare and upload just those two, then:

{
  "action": "publish",
  "app": "my-app",
  "base_revision_id": "<pinned-base-revision-id>",
  "manifest": {
    "format": 1,
    "documents": [
      {"path": "billing.md", "content_hash": "<edited-sha256>", "bytes": 1234},
      {"path": "local-development.md", "content_hash": "<edited-sha256>", "bytes": 2345}
    ]
  },
  "uploads": [
    {"contentHash": "<billing-edited-sha256>", "uploadId": "<verified-upload-id>"},
    {"contentHash": "<development-edited-sha256>", "uploadId": "<verified-upload-id>"}
  ]
}

Calculate hash and byte count from the edited file, or use the verified upload’s metadata. The initial prepare_edit hash/size no longer apply after editing. Submit uploads at most two at a time and wait for verification. The resulting candidate contains all nine pages. Its returned manifestHash commits the complete nine-page result, including the two changed pages. The base must have a complete format-1 manifest in the same team/application; no fallback to latest or automatic root selection occurs. Without base_revision_id, manifest is the complete selection and requires a verified upload for every distinct hash.

Base validation failures return a publication-specific rejection code and guidance; no mutation was forwarded. Inspect the pinned revision instead of choosing another base automatically. Pre-manifest revisions require an explicit full publication before they can serve as a format-1 base. If a daemon or server rejects the new base argument, check that both versions support it. Rejection or unavailability alone does not diagnose version skew; reconcile the same IDs before retrying, and never drop the base or replay the publication automatically.

Reconcile operation with app, publication_id and the exact returned manifest_hash. A matching receipt attempts cleanup after verifying the complete manifest. Each pass checks at most 128 draft directories; repeated reconciliations in the same MCP session continue through the remaining drafts. Inspect temporary_edits: if it is absent, verification or cleanup was unavailable. Reconcile the same publication again when needed; a published revision remains accepted even if cleanup is deferred. Retain any returned temporary_edits.recovered_file_paths if an edit changed during cleanup. temporary_edits.retained_file_paths identifies interrupted copies that could not be restored safely; preserve those bytes and inspect their file permissions or links; do not delete unresolved copies.

Immediately after a pending publication, operation may report unconfirmed with reason: "receipt_not_observed" and retry_after_ms: 2000. The receipt may still be completing or replicating; this observation is not a rejection. Wait the suggested interval before polling; it is a polling hint, not a completion deadline. Poll the same publication and manifest hash, and inspect its retained operation ID for a definite rejection. Do not submit another publication merely because its receipt is not visible yet. A failed receipt lookup returns reason: "lookup_unavailable" with connection and polling guidance; it does not report rejection or acceptance.

Inspect the publication receipt with the returned IDs and manifest hash, then select its root explicitly using the observed root’s revision and change token. Do not rebase or repeat an uncertain root change automatically.

Load knowledge-corpus for the current publication and review contract. prepare_edit and this upload workflow are local MCP actions; there is no matching reflow knowledge CLI command. The knowledge-maintainer profile can prepare edits, upload and publish candidates, but cannot delete reservations or select roots.

revisions defaults to 50 entries and honors limit and offset within the newest 100 revisions visible in the bounded library window. next_offset is null at the end of that window; it does not assert that no older history exists.