DEV-7314: feat(knowledge): sync knowledge folder in sandbox and workspace push/pull#23
Merged
Conversation
xanojustin
approved these changes
Jun 25, 2026
Add workspace knowledge (agents.md, skills, docs) to `workspace pull`
and `workspace push`, mirroring the multidoc model: the backend returns
structured knowledge objects via `GET/POST workspace/{id}/knowledge/sync`
and the CLI owns the on-disk `knowledge/` layout and YAML frontmatter.
- new src/utils/knowledge-sync.ts: fetch/push/write/collect knowledge
objects, build/parse frontmatter, guid writeback, client-side diff
fallback when the server dry_run is unavailable
- multidoc-push.ts: optional knowledge hook folds knowledge into the
single combined push preview + confirmation; honors branch,
--sync/--delete, --dry-run, --include/--exclude, --guids
- workspace push/pull wired to .../knowledge/sync (sandbox unchanged)
- each distinct object gets a unique folder so duplicate names can never
silently overwrite (identity travels via frontmatter guid)
- README + tests (79 passing)
Verified end-to-end against a local instance: pull, create, update,
idempotent re-push, and --sync --delete all round-trip correctly.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Extend knowledge sync to `sandbox push`/`sandbox pull`, mirroring how the workspace commands do it. Both target `.../api:meta/sandbox/knowledge/sync` (no workspace id, branch=""), fold into the same combined push preview, and degrade gracefully (404 → no-op) until the backend adds the sandbox endpoint. - sandbox pull: fetch + write knowledge objects after the multidoc split - sandbox push: pass the knowledge config to executePush - README: note knowledge sync on sandbox push/pull Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The knowledge/sync API requires description/scope/mode/enabled on every item; the CLI previously omitted them when a file's frontmatter had none, so minimal/hand-authored knowledge files failed with a 400. Default them (description="", scope="workspace", mode="auto", enabled=true) when absent. Pulled files already carry these, so round-trips are unaffected. Verified end-to-end: a minimal doc (name + knowledge_type only) now passes the server dry_run (200, authoritative preview — no client-side fallback) and creates + writes its guid back. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…owledge sync Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…s empty Previously, pushing a knowledge-only directory with all files removed (triggering a delete-all via --sync --delete) would throw "No .xs files found" because knowledgeOnly required knowledgeObjects.length > 0, and the push/dry-run/summary guards all gated on the same condition. Now all three guards also fire when shouldDelete is true, so an empty local knowledge tree correctly sends items:[] with delete:true to the server. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Clear multidoc when filteredEntries is empty on a partial push so a knowledge-only change doesn't also POST the full .xs document set - Guard the multidoc POST against an empty body to skip it entirely - Add scope to canonical() so scope-only frontmatter edits are caught by the client-side dry-run fallback change detection Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
xano-izzy
force-pushed
the
knowledge-tree-api-cli
branch
from
b80b449 to
e3ca34f
Compare
xano-izzy
changed the title
- sandbox/pull: restore 'No documents found in response' guard (without early return so knowledge still pulls when documents are empty) - sandbox/push: restore delete flag to its original position after directory flag Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…ox examples Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
src/utils/knowledge-sync.ts: pull/push logic foragents.md,skills/, anddocs/knowledge folders — YAML frontmatter parsing, GUID writeback, dry-run support, and--sync --delete(full-sync) mode.workspace pull/push(viaGET/POST /api:meta/workspace/{id}/knowledge/sync) andsandbox pull/push(viaGET/POST /api:meta/sandbox/knowledge/sync).test/utils/knowledge-sync.test.ts(288 lines, 80 tests passing).README.mdwith knowledge sync behavior for both commands.Backend dependency
Workspace path (
workspace pull/push) is fully testable today.Sandbox path (
sandbox pull/push) depends onGET/POST /api:meta/sandbox/knowledge/syncbeing deployed. The CLI gracefully no-ops (skips knowledge) when the endpoint returns 404, so this is safe to merge before the backend ships. A test runbook for the E2E validation is at.context/sandbox-knowledge-test-runbook.md— hand it to a test agent once the endpoint is live.Test plan
npm run build— clean compilenpm test— 80 mocha tests pass (lint failures are pre-existing onmain, none introduced by this branch)xano workspace pull -d /tmp/wstest --verbose— verifyknowledge/layout and frontmatterxano workspace push -d /tmp/wstest --dry-run --verbose— server-side dry-run 200, preview output.context/sandbox-knowledge-test-runbook.mdonce backend endpoint ships🤖 Generated with Claude Code