[nplez1]

	Files	Added	Deleted	Net
Test	0	0	0	0
Prod	2	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​108	0	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​108

ELI5

I have one main machine and several paired Orca hosts. Right now each host has to be configured by
hand — its own settings, its own Jira and provider connections. I want the main machine to be
authoritative: it pushes its settings to the paired hosts, and they mostly just use them.

This PR is only the design. It writes down the shape, why the obvious alternatives are wrong, what
already exists to build it on, and the questions that have to be answered before anyone writes code.
No behaviour changes.

What Changed

Before: nothing was written down. The idea had been discussed only in conversation, and the
tempting shortcut — "just resolve credentials across hosts when someone reads a ticket" — is
subtly wrong in a way that would have been discovered late.

After: docs/reference/host-settings-replication.md records the proposal, and this fork's
.gitignore allow-lists it (reference docs are listed by name there).

Why

Replication, not proxying. The main laptop is often asleep. If a paired host resolves
credentials by asking the main, its ticket panel simply stops working whenever the laptop is away.
So each host holds its own copy — which is also why local and ssh:* reads being served by the
local app today is not the same thing.

Build on what exists. Profile transfer already moves a profile between hosts, and
profile-project-session-field-disposition.ts decides each field's fate through explicit axes
(onRepoRemoval, onTransfer). Replication is a third axis on that table, with the values
replicated / hostLocal / replicatedOnlyIfEmpty — plus cloud profiles as the identity layer.
The new part, and the risky one, is that nothing in orca-profiles transfers credentials today.

Two things worth knowing before the work starts. First, it is blocked on a path fix: the Jira,
Jenkins, Bitbucket, zcode, API-key and floating-workspace stores still hardcode ~/.orca, which
this fork's own directory module says would let an official Orca install read, migrate or clobber
this fork's state — replicating settings into a shared directory would corrupt both installs.
Second, secrets are the hard part: a replicated token is stored on the receiver, revocation has to
delete it on every host that received it, and a weaker keyring silently downgrades at-rest
protection.

An issue would have been the natural home for this, but this fork has issues disabled, so a tracked
document is the durable capture.

Linked Issue

N/A — issues are disabled on nplez1/orca.

Visual Proof

N/A — documentation only; no UI or behaviour change.

Testing

• I manually tested these changes locally
• Automated tests added/updated, or explained why not below

Docs only: no code, tests or behaviour changed. pnpm tc, oxlint and the changed-lines gate are
unaffected; the only non-doc change is a .gitignore allow-list entry.

AI Disclosure

Claude (Anthropic) wrote this document from the fork owner's description of their topology, and
checked its claims (the disposition table, the hardcoded .orca paths, the capability surface)
against the code.

Review

Self-reviewed. The claims in the document about existing machinery cite the files they come from.

Agent skill upstream boundary

• Not applicable, or this change follows docs/reference/agent-skill-sharing-upstream-boundary.md and copies or mechanically translates no upstream skill-installer source, tests, fixtures, registry entries, path tables, comments, or documentation.

Notes

• Security. The document's central risk is secret replication; it explicitly refuses to leave
  that implicit.
• Cross-platform / SSH / remote / mobile. The proposal is about paired hosts generally,
  including remote ones; the wire rules it must follow are referenced rather than restated.
• Backwards compatibility. Nothing here changes behaviour or the wire today.

Checklist

• This PR is small and focused
• I explained what changed and why (ELI5, the user-facing before/after, the mechanism, and why over the alternatives)
• Before/after screenshots or videos attached for UI changes, or N/A with reason
• Self-reviewed for correctness, security, and performance
• Cross-platform, SSH/remote, and path/shortcut impact considered (or N/A)
• pnpm lint, pnpm typecheck, pnpm test, and pnpm build pass (or CI will cover; local preferred)

[nplez1]

Closing in favour of #54, which now carries the full proposal — issues were disabled on this fork when I opened this, so a tracked doc was the only durable capture. The working note stays local at docs/reference/host-settings-replication.md (the fork's .gitignore keeps design notes for unbuilt work out of the tracked set, and reference docs are allow-listed by name), and the issue body is a verbatim copy of it. Promoting the note into the tracked set — a .gitignore entry plus an AGENTS.md link — is a one-commit follow-up whenever the work starts.

[nplez1]

Correction to the closing comment: the working note does not stay local at that path. Deleting this branch removed it — switching back to the Jira branch deleted the file, since it was tracked here and untracked there. I restored it from issue #54's body, so the working tree matches the issue again.