Skip to content

docs(skills): describe relayfile schema-discovered writeback #30

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
khaliqgant merged 2 commits into from
May 13, 2026
+18 −3
Merged

docs(skills): describe relayfile schema-discovered writeback #30

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0d2c3bd
docs(skills): describe relayfile schema-discovered writeback
khaliqgant May 7, 2026
dffb6de
docs(relayfile): resolve writeback skill conflicts
khaliqgant May 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 18 additions & 3 deletions skills/setting-up-relayfile/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ Relayfile mounts a provider (Notion, Linear, Slack, GitHub, and other adapter-ba

After setup, files appear under `<local-dir>/<provider>/...`:

```
```text
~/relayfile-mount/notion/
├── databases/
│ ├── <slug>--<id>/
Expand All @@ -35,6 +35,8 @@ After setup, files appear under `<local-dir>/<provider>/...`:

Read = `cat`. Write = overwrite, create, or remove files in writable adapter resource directories. The mount daemon picks up the change, queues a writeback, and the cloud delivers to the provider's API.

Current mounts are also self-describing. Start with `<local-dir>/LAYOUT.md`, then read provider-specific `<provider>/.layout.md` files and nearby `_index.json` files instead of hard-coding paths from memory. Entity filenames may use a `<sanitized-name>__<id>` convention, and some providers expose alias views such as `by-title/`, `by-id/`, `by-name/`, or `by-state/`.

## Prerequisites

- Recent `relayfile` CLI on `$PATH`. Verify: `relayfile --help` should list `setup`, `integration`, `writeback`, and the `integration available` / `integration search` / `integration set-metadata` subcommands.
Expand Down Expand Up @@ -68,7 +70,7 @@ relayfile status my-agent
```

Healthy output:
```
```text
workspace rw_xxxxxxxx (my-agent) mode: poll lag: 4s

local mirror: /Users/you/relayfile-mount
Expand Down Expand Up @@ -104,6 +106,8 @@ export RELAYFILE_LOCAL_DIR=~/relayfile-mount

Mental model for the agent: ordinary files. Use `Read`, `Write`, `Edit`, `Glob`, `Grep` — same as any project directory. Writes propagate within ~30s.

Before writing, read the relevant `_PERMISSIONS.md` or discovery files for the target subtree. If a path is denied, Relayfile preserves the local copy and records the denial in `<local-dir>/.relay/permissions-denied.log`.

### Pattern B: remote agent / SDK access (no disk mirror)

Use `@relayfile/sdk` against the workspace token:
Expand Down Expand Up @@ -145,6 +149,16 @@ If the marker doesn't appear in step 4, see **Recovering from breakage**.

Do not guess writeback shapes and do not use a magic `new.json` filename. Current relayfile adapters ship discovery documents for writable resources:

A typical discovery surface looks like:

```text
<provider>/
├── .adapter.md ← adapter overview, operations, ID patterns
└── <resource>/
├── .schema.json ← full-record JSON Schema, draft 2020-12
└── .create.example.json ← minimal create payload
```

- First check which writeback contract the mounted workspace exposes. Run `find "$RELAYFILE_LOCAL_DIR" \( -name '.adapter.md' -o -name '.schema.json' -o -name 'new.json' \) | head -40`. If discovery files are absent and `new.json` templates are present, the mounted workspace is still on the pre-file-native adapter bundle; do not apply the create-by-filename flow until the cloud/adapter deployment has refreshed that workspace.
- Read the provider `.adapter.md` first. In mounted workspaces this may appear under the provider tree or under `<local-dir>/discovery/<provider>/.adapter.md`; if unsure, run `find "$RELAYFILE_LOCAL_DIR" -path '*/.adapter.md'`.
- Read the resource `.schema.json` before writing JSON. It is JSON Schema draft 2020-12 for the full synced record. Fields with `"readOnly": true` are server-managed and must not be written. Common schema paths are resource-local, such as `/linear/issues/.schema.json`; packaged adapters also carry a discovery copy under `discovery/<provider>/...`.
Expand Down Expand Up @@ -264,13 +278,14 @@ Workspaces created by the productized cloud-mount flow are `rw_<8hex>`. Older wo

### G6 — Mount mirror dir conventions

```
```text
<local-dir>/
├── <provider>/... ← actual files
├── .relay/
│ ├── state.json ← daemon's live state (workspaceId, lag, counters, remoteRoot)
│ ├── integrations/<provider>.json ← per-integration metadata
│ ├── dead-letter/<opId>.json ← failed writebacks (Phase 1 dead-letter)
│ ├── permissions-denied.log ← read/write denials preserved for diagnosis
│ ├── disconnected/<provider>.json ← marker after `integration disconnect`
│ └── conflicts/<resolved-conflicts>
└── .relayfile-mount-state.json ← sync revisions per file
Expand Down