Files and versions

When you edit a workspace file, check which copy you are changing and which copy your running analysis uses. Querio has shared canonical files, separate working copies and immutable snapshots. Publishing changes shared files; opening a pull request does not.

File targets and execution

In Settings > Git, File mode is labeled Shared files (canonical) or Branches (changeset). The API keeps those technical values. The workspace's fileMode determines environment selection. In canonical mode, the environment uses shared files; this is the default when no mode is configured, and supplying a changeset is rejected. In changeset mode, the environment uses a specified working copy or creates one from the default source. The environment keeps that binding and cannot switch to another copy.

A session runs against its environment's selected directory. Closing the environment releases its attachment but leaves the working copy in place. You cannot discard a copy while it is attached. See Environments, sessions and runs for the runtime lifecycle.

File paths start at the workspace root, not automatically at [context].root. If root = "querio/", for example, memory's workspace-relative path is querio/memory/MEMORY.md. See Context files for the current tree and loading rules.

Context reload versus source changes

/reload reads context and skills again from the directory already selected by that session. It does not switch working copies, import or publish a version, reconcile a base, or rerun notebook cells. If an edit is missing from a conversation, check that session's file target first. Publishing to canonical files does not refresh an existing working copy. Saved and live analysis state are described in Explores and conversations.

Versions and working copies

These are Querio versions, not Git commits. A working copy is not a Git branch. Version and changeset IDs are opaque Querio IDs; a file's revision or HTTP ETag is a separate change token, not a version ID or content hash.

Edits survive reopening a working copy without a checkpoint. A checkpoint pins the bytes used for export or publication: if you checkpoint approved and then edit the file to draft, publishing that checkpoint uses approved.

Status compares current working files with their base and shows the latest checkpoint and canonical version. It does not update the base. Changed paths remain visible when binary content or a file pair larger than 512 KiB cannot show an inline text diff.

Publication and conflicts

Publication applies a pinned snapshot to canonical files. It does not update other working copies. Publishing a copy's latest checkpoint can advance that copy's base while preserving edits made after the checkpoint. New default copies start from current canonical state, or from the promoted source when Git manages the workspace.

Publication requires the expected canonical version to be current. A non-Git checkpoint must also have the current canonical state as its base; supplying a newer expected version cannot bypass that check. A base update can merge non-overlapping text changes, but unresolved conflicts leave the working files and base unchanged. Restoring a checkpoint restores its original base and files.

Review the complete diff and pause other writers before capture or publication. A single file replacement is atomic, but publication across files is not: failure can leave some canonical files changed without selecting the published version. Inspect the actual files, refresh canonical state and reconcile the difference before retrying. Do not retry a stale or failed publication blindly.

Git-backed source

GitHub integration is available to all customers; connecting a repository requires permission to manage workspace settings. Use Git and CI sync owns the connection, review and CI procedure. Get the Querio CLI; command syntax is in the CLI reference.

• Git upload selects committed bytes with repository-relative [context].include and [context].exclude patterns; exclusions win. [context].root locates context but does not limit upload selection.
• Import records the supplied repository, commit and configuration identity. The file store does not fetch the repository or verify approval or commit ancestry. Import alone does not publish.
• A Git-backed working copy keeps its original source base. Export selected edits as a patch, reconcile them in Git and import the resulting commit. It cannot be rebased onto a different source in Querio.
• Promoting an imported Git version removes previously Git-managed files absent from the new source, preserves unrelated canonical files and rejects conflicting unmanaged paths. Existing working copies remain unchanged.
• Once Git manages canonical source, a non-Git snapshot cannot replace it. A Git working-copy checkpoint is not an imported commit eligible for direct promotion.

Patch, pull request and publication

File operations

Canonical operations use /api/v3/files/*. Environment operations use /api/v3/environments/{environment_id}/files/* and require an active session bound to that environment, with matching workspace and session headers. Changeset file operations select the working copy explicitly. A session header on a canonical request does not change its target. See the API reference for request shapes.

Write intent and revisions

Choose one write form:

Do not combine flags with revision headers. Remove and rename also accept If-Match: * for an unconditional operation. Conditions apply to the named entry, not a multi-file transaction. If a response is lost, read the current state before repeating the mutation.

Limits, reserved paths and permissions

Raw file writes cannot create or write through symbolic links. They also do not turn data files into queryable tables; use Upload files for analysis for ingestion and result checks.

File reads, writes, deletion, rename and directory creation use separate workspace file permissions. Promotion requires write and delete permission; working-copy promotion also requires read permission. Choosing a workspace, environment or changeset does not grant file access. Datasource query permissions are separate; see Users, roles and groups.

Operation history records successful version operations and supplied attribution. It does not establish who wrote each byte or provide a tamper-proof audit log. Closing compute does not delete version history; automatic reclamation of retained version objects is not implemented.