Menu

Shared corpora and collaboration

Ordinary folders as explicit trust boundaries

Org2 collaboration starts with a small rule: do not share a person's entire private corpus merely because one project or teammate needs shared context. Put routinely shared notes, tasks, meetings, decisions, workflows, and review records in a separately mounted shared corpus.

A corpus remains an ordinary folder or repository. Transport and membership can come from Git, a file-sync provider, or operating-system permissions. Org2 does not present descriptive metadata as a replacement for those enforcement layers.

Portable corpus identity

An identified corpus carries a small portable record inside org2.json:

{
  "corpus": {
    "schema": "org2:corpus:v1",
    "id": "team-operations",
    "name": "Team Operations",
    "kind": "shared"
  }
}

The ID is stable across clones and local mount paths. The name is human-facing. The initial kinds are personal, shared, and project. Credentials, local paths, and membership do not belong in this portable record.

Inspect or validate an existing corpus with:

org2 corpus show --dir ~/notes --json
org2 corpus validate --dir ~/notes

Add identity to a new or existing corpus with a preview-first command:

org2 corpus init --dir ~/team-operations \
  --id team-operations \
  --name "Team Operations" \
  --kind shared

# After reviewing the preview:
org2 corpus init --dir ~/team-operations \
  --id team-operations \
  --name "Team Operations" \
  --kind shared \
  --apply

Applying creates the standard visible zones when missing and merges the identity into org2.json. It refuses to replace a different existing ID unless --force is explicit.

Mac workspace mounts and federated reads

Org2 Workspace remembers every corpus you open. The compact switcher at the bottom of the sidebar shows the active corpus name and switches among mounted local paths; full identity and path metadata stay out of the navigation until needed. Create a shared team corpus makes a starter folder with a portable shared identity.

The Agenda and text Search surfaces can read either the active corpus or all mounted corpora. Federated rows carry the portable corpus identity and show the corpus name beside the source path. Opening a row from another corpus activates that corpus before loading the entry.

Writes remain scoped to the explicitly active corpus. Capture, bulk agenda changes, source edits, AI-chat context, workflows, runs, approvals, and meetings do not acquire a workspace-wide destination. A cross-corpus agenda row must be opened, and its corpus therefore activated, before it can be edited. The local mount registry stores paths on that Mac; it is app configuration, not portable corpus content.

This does not merge corpora into one database. The shared CLI runs the canonical agenda or search engine against each explicitly supplied corpus, then combines the deterministic JSON results and attaches identity. Agenda semantics remain in the same compiler/runtime path used for a single corpus.

Automation can request the same read-only projection with repeatable mounts:

org2 workspace agenda \
  --mount ~/personal-notes \
  --mount ~/team-operations \
  --recursive --from 2026-07-20 --to 2026-07-26 --json

org2 workspace search "launch readiness" \
  --mount ~/personal-notes \
  --mount ~/team-operations \
  --recursive --limit 50 --json

Every eligible mount needs a valid portable identity. The payload reports invalid or unavailable mounts under issues instead of quietly treating a local path as identity. Duplicate corpus IDs are rejected from the combined projection.

A practical team pilot

For an initial small-team rollout:

  1. Create one shared corpus for one real workflow or project.

  2. Put only the context collaborators routinely need in that corpus.

  3. Share the folder or repository using infrastructure the team already trusts.

  4. Have each collaborator mount both their personal corpus and the shared corpus in Org2 Workspace.

  5. Use all-corpora Agenda and Search for awareness. Keep personal quick capture in the personal corpus's daily note; switch to the shared corpus before creating shared tasks, notes, runs, or workflows.

  6. Give an agent only the shared corpus path when it should not receive personal context.

The shared artifact should make sense on its own. A link into an unmounted private corpus is not a substitute for the minimum context a teammate or scoped agent needs.

Safety boundary

  • Corpus identity describes the boundary; filesystem, repository, sync, and encryption controls enforce access.

  • An agent must receive an explicit corpus path or future workspace profile. It must not inherit every corpus visible to a person by convenience.

  • Federated CLI reads require every mount to be named explicitly. A remembered human workspace does not silently expand an agent's scope.

  • Generated work should stay in views/ or compiled/ until reviewed for promotion.

  • Org-crypt can restrict exceptional subtrees within a corpus, but it is not the default collaboration interface.

  • Local mount paths and inaccessible source details must not be copied into portable shared artifacts.

What comes next

The next collaboration layers build on this identity, mount, and federated-read boundary:

  • previewable handoff from a private corpus into a shared corpus;

  • explicit workspace profiles for people, agents, and automation;

  • coarse read, proposal, generated-zone, and direct-write policies at Org2 command boundaries.

Real-time collaborative editing and hosted identity are not prerequisites. The near-term goal is coherent ownership, handoff, review, and agent scoping over files the team already controls.

Related