# Work offline

[All tutorials](/docs/tutorials.md) · [Client workflow reference](/docs/client-usage.md#offline-work-and-reconciliation)

You will edit a tracked file without a server connection, reconnect, acquire its
required lock, and submit the result. Offline editing preserves local work but
cannot reserve a file against other users. For a planned disconnect, acquiring
locks beforehand gives stronger protection.

The walkthrough continues [1. Minimal server](/docs/tutorials/01-minimal-server.md), before adding
authentication. It uses that tutorial's `game` repository and Alice/Bob working
copies. Run deployment commands from `scribe-demo`; parentheses below change into
a working copy and return automatically. Use matching client/server binaries that
support `edit --offline` and `reconcile`.

For an existing team workspace, use your own tracked file and configured endpoint
instead. Skip the demo policy and server shutdown steps; leave shared services
running. Files must already be downloaded. Creating a workspace, fetching missing
content, acquiring locks, and submitting require a server connection.

## 1. Prepare the demo while connected

If you finished the minimal-server tutorial, start storage A again:

```sh
scribe-ctl --config scribe-cluster.toml up
```

Then make the demo hero require a lock and sync Bob's copy:

```sh
(
  cd work/alice-plain
  mkdir -p .scribe
  printf 'version = 1\n[locks]\nrules = ["Assets/Hero.txt"]\n' > .scribe/config.toml
  scribe add .scribe/config.toml
  scribe submit -m "Require a lock for the demo hero"
)
(
  cd work/bob-plain
  scribe sync
  scribe lock rules Assets/Hero.txt
)
```

Check that the rule query reports a required lock. This creates the policy in the
fresh demo; do not overwrite an existing team's `.scribe/config.toml`. In an authenticated
repository, activating main-branch policy changes requires Maintainer permission.
The accepted policy on **main** governs every branch.

## 2. Disconnect and edit locally

Stop only this local demo server:

```sh
scribe-ctl --config scribe-cluster.toml down
```

Now open and edit Bob's local file:

```sh
(
  cd work/bob-plain
  scribe edit --offline Assets/Hero.txt
  printf 'hero mesh edited offline\n' > Assets/Hero.txt
  scribe status
)
```

Check that status reports the file as modified and **pending reconciliation**.
`edit --offline` records the intent before making a read-only file writable. It
makes no connection and acquires no lock. Ordinary `edit` would fail while the
server is unavailable; it never silently switches to offline mode.

You can keep editing opened files and run local `status` or `scan --verify`.
Local `add --offline`, `delete`, and `move` are also available, subject to their
normal workspace protections. A plain `add` records the file too, but first
tries the server to lock it and reports the check as skipped. An unknown submit outcome must be resolved online before
starting new local operations; keep its pending state intact.

## 3. Reconnect and reconcile

Start the same server again with `scribe-ctl --config scribe-cluster.toml up`.
In Bob's workspace, reconcile the local work:

```sh
(
  cd work/bob-plain
  scribe reconcile
  scribe status
)
```

In this demo, reconciliation reports the hero as ready and its pending marker
clears. It checked the workspace branch's server revision and acquired the lock
required by the current main policy. Your edited bytes and local base remain
unchanged.

If a connection fails during reconciliation, retry the command. Successfully
acquired locks stay held, even if their replies were lost; retrying an acquisition
still owned by this workspace is safe. Inspect `scribe lock list` when you need to see
what is held. Readiness is a check at the reported revisions, not a guarantee
against later policy changes, new revisions, or administrative lock revocation.

## 4. Submit and verify from Alice's copy

```sh
(
  cd work/bob-plain
  scribe submit -m "Update hero after offline work"
  scribe lock release Assets/Hero.txt
)
(
  cd work/alice-plain
  scribe sync
  cat Assets/Hero.txt
  scribe log Assets/Hero.txt
)
```

Alice's file should contain `hero mesh edited offline`, and its history should
include Bob's new change. Submit independently enforces current revisions and
lock ownership. Locks survive successful submissions, so Bob explicitly releases
the hero after finishing. If submit reports an unknown outcome, rerun submit to
resolve it before continuing.

## When someone else changed or locked the file

On a shared server, reconciliation can report several blockers for one file.
A blocked run exits 1 and keeps local content. Unrelated ready paths can still
complete reconciliation; acquired locks remain held.

- **Locked:** coordinate with the holder and retry after they release the lock.
  Offline editing grants no right to take another workspace's lock.
- **Server changed:** run `scribe resolve --update`, then `scribe resolve` to
  inspect the remaining conflicts. Review automatic text merges; binary assets
  may need an external editor or an explicit ours/theirs choice.
- **Missing or reappeared file:** restore a missing edit, or explicitly record the
  intended deletion. Preserve a reappeared file before deciding what to delete.

After editing an unresolved hero to the desired result, record the choice and
check again:

```sh
scribe resolve --working Assets/Hero.txt
scribe reconcile
scribe submit -m "Resolve offline hero changes"
```

Run those commands inside the affected workspace, after starting resolution with
`resolve --update`. If a pending move's source advanced, abort dependent moves in
reverse order, resolve the source, and repeat the move. Automatic updating of
pending move sources is not supported.

For a grouped merge rejected because the target advanced, abort and restart the
merge instead of using `resolve --update`. Retain and reapply recovered manual
edits as needed. See [rename-aware merging](/docs/client-usage.md#rename-aware-merging).

## Collect changes made outside Scribe

If an editor changed a tracked file before you opened it, first inspect locally,
then collect tracked edits when connected:

```sh
scribe scan --verify
scribe reconcile --scan
```

Run these inside your workspace. `--scan` hashes tracked contents, opens discovered
modified tracked files, and reconciles them. This can take time on a large project.
It reports untracked and missing files separately: use explicit `add`, `delete`,
and `move` to express those intentions. It never guesses a rename or turns every
missing file into a deletion. Exit 0 means all **opened** paths passed; separately
reported untracked or missing discoveries may still need your attention.

## Prepare for your next offline session

While connected, sync the files you will need and open required assets normally:

```sh
scribe sync
scribe edit Assets/Hero.txt
```

The normal edit acquires a required lock before opening the file. Keep that lock
while disconnected; already-opened files remain editable offline. For an optional
path that you also want to reserve, run `scribe lock acquire Assets/Hero.txt` explicitly
before editing. When back online, reconcile, submit, and release locks you no
longer need.

See the [offline workflow reference](/docs/client-usage.md#offline-work-and-reconciliation)
for exact state and retry behavior, and [JSON output](/docs/json-output.md) for
scripting reconciliation reports.