Onboarding

#Intended first outcome

A new Wisent developer verifies and opens an exact Tama release, signs in, inspects the bundled policy without changing the machine, explicitly installs local enforcement, and sees one supervised agent session reported as kernel-gated with matching hook release identity.

#Prerequisites

Required for every supported installation:

• Apple-silicon Mac running macOS 14 or newer; check with uname -m and sw_vers -productVersion;
• a Wisent account with a current owner, admin, or member role in the selected organization; unknown or absent roles cannot open controls;
• access to the private wisent-ai/tama-desktop GitHub releases;
• at least 500 MB free local storage; check with df -h "$HOME".

Required for local enforcement or repository scan/cleanup:

• Node.js 20 or newer available on PATH, /opt/homebrew/bin, /usr/local/bin, or ~/.local/bin.

Required only for local enforcement:

• Python 3 available at /usr/bin/python3;
• permission to approve Login Items, a System Extension, Network filtering, and Full Disk Access in macOS settings.

Required only for agent-assisted cleanup:

• an installed and authenticated local codex agent;
• a working git CLI so Tama can reject HEAD, checked-out branch, or local branch-ref mutation;
• a cleanly recoverable repository working tree owned by the current user.

The release supplies the app, hook catalog, hook runtime, violations CLI, daemon, and Network Extension. A source checkout is never a prerequisite for a supported installation.

#Install an exact release

No supported preview is currently published. Once a preview is marked supported in its release notes:

1. Download the exact zip, digest file, provenance JSON, and release notes from https://github.com/wisent-ai/tama-desktop/releases/tag/v<SemVer>.

2. Confirm the provenance productVersion, sourceRevision, platform, and architecture match the release and this Mac.

3. In the download directory run:

   shasum -a 256 -c Tama-<version>-macOS-arm64.zip.digest
   

   Expected output:

   Tama-<version>-macOS-arm64.zip: OK
   

4. Expand the zip and move Tama.app to ~/Applications/Tama.app. Elevated privileges are not required.

5. Open the app through Finder. Confirm any Gatekeeper prompt names Tama and the expected Wisent signing identity.

Installation does not register services or modify agent configuration.

#Optional existing-policy import

The first screen offers Choose bundle and Skip. Choose an existing self-contained Tama policy bundle or sealed release directory with a regular shared-hooks/registry.json. The same operation is available later in Settings → Policy bundles and from the CLI:

tama onboarding --policy-bundle /absolute/path/to/bundle
tama policy import --source /absolute/path/to/bundle
tama policy list --json

The accepted self-contained policy bundle or sealed release contains a regular shared-hooks/registry.json and regular, non-symlink files under shared-hooks/, claude-hooks/, codex-hooks/, repo-githooks/, adaptive/, external-hooks/, and bin/, plus supported root metadata such as release.json and external-sources.json. Other top-level paths appear in ignoredPaths; they are not silently accepted as policy. The complete registry and every registered source are checked before mutation, and a sealed release must match its release.json tree identity. Invalid JSON, missing sources, seal mismatches, symlinks, and special files reject the bundle without partial writes.

Source path and ordered file content form a stable SHA-256 identity. Repeating identical content is unchanged. A differing stored bundle reports the complete conflict list and writes nothing unless replacement is explicitly requested. Replacement still protects untracked and locally changed stored files.

Successful import writes an editable bundle plus index.json under ~/Library/Application Support/Tama/policy-bundles. The index keeps the source path, digest, time, hooks, files, modes, and per-file hashes. Imported means inactive: the operation installs and enables zero hooks and does not touch the active release, runtime, agent adapters, Git configuration, or source directory. Skip leaves an empty, usable Tama.

#Sign-in and setup

Tama opens Wisent authentication directly. The read-only bundled-policy inspector remains an explicit toolbar choice and uses an isolated catalog model that does not read installed-policy, backend, session, or repository state.

Enter the Wisent account email and request a one-time code, or use an enabled delegated provider. Credentials and refresh tokens are stored by Wisent Auth in the macOS Keychain. Tama does not store them in Application Support. A successful Wisent Auth state is the sole source of authentication truth; Tama does not duplicate it in preferences.

After authentication, the full control interface opens immediately — there is no separate setup gate — and the signed first-use journey records tama.hasCompletedSetup only against visible setup evidence (desktop/setup). Runtime installation, privileged backend registration, macOS approvals, and live-session verification remain separate explicit actions. If identity is unavailable, the read-only inspector remains usable. All runtime, service, session-control, emergency, and repository workflows remain behind authentication and their explicit mutation boundaries.

#First successful workflow

Starting state:

• Tama is installed and signed in;
• no Tama runtime is installed;
• no Tama daemon or Network Extension is registered;
• no supervised agent is running.
• Node.js 20 or newer and /usr/bin/python3 are available in the documented locations.

Steps:

1. Open Settings → Local enforcement and confirm the starting state: Installed release reads Not installed by Tama and Privileged backend reads Not registered.
2. Select Install local runtime (enabled only while the bundled catalog validates). After release-integrity validation and before any managed write, Tama resolves Node from the documented locations, rejects versions older than 20, canonicalizes the executable through symlinks, and pins it into every Node-based installed hook command and the generated supervisor launcher. Each installed hook and supervised semantic dispatch preloads the sealed version guard before its target script. Tama also checks the Python installer prerequisite before launch. The mutation bar reports Installing the integrity-checked hook runtime… then Installed hook release <id>.
3. If managed hooks are globally disabled, Posture → Re-enable all hooks verifies the bundled release, restores every managed dispatcher, and reports Every managed hook dispatcher is active again.
4. Select Register privileged backend in Settings. Approve the daemon/System Extension and Network filter in macOS settings via Approval settings, and grant Full Disk Access only to the named Tama component via Full Disk Access.
5. Start or resume one supported supervised coding-agent session using its normal launcher, then select Refresh sessions on Session.
6. Confirm the setup evidence shows:
   • bundled policy valid;
   • local runtime installed and enabled;
   • privileged backend enabled;
   • installed and loaded release identities match;
   • loaded hook count equals the nonzero registered hook count;
   • no disabled or unknown hook IDs, registry error, pending reload, or reload requirement;
   • system policy is Kernel-gated.
7. The first-use journey records the verified setup handoff (tama.hasCompletedSetup) once exactly that evidence is visible; there is no separate confirmation button, and nothing else records it.

The control interface opens on Posture, the default destination. That visible, matching setup evidence is the first successful product outcome. An acknowledgement, successful login, install exit code, or partial backend registration is not sufficient.

#Machine onboarding

Tama does not expose an unattended enforcement-setup API. Its tama request policy-bundles/import operation can adopt an inactive policy bundle, but nothing can install or enable that bundle without a person. Automation may read published provenance and hook-release manifests, while a human must verify the artifact, sign in, confirm runtime installation, and approve every privileged macOS component. After that setup, supervised agents use versioned capability records in ai.wisent.tama.session-control.v2; each record is bound to a session, control key, catalog checksum, release ID, lifetime, and remaining-use limit. Missing or expired capability records fail closed and do not trigger setup automatically.

#Optional repository scan

Choose the repository in Repository in view in the sidebar header — a directory owned by the current user — then open Violations and select Scan. The scan is read-only. Select Stop scan to cancel its bounded process tree without changing the repository. Success is a report with file counts and either explicit rule violations or zero violations. Scanner errors and skipped files remain visible, and the rule rail counts how many files each rule hit.

Repair is separate and mutating, and it opens a decision dialog that lists every file the repair would edit. Back up or commit unrelated work first, read that list, and review the resulting working-tree diff yourself. Each round asks the Brama route Tama resolves for one patch, applies it and scans again (violation repair).

#Common failures

Errors should say whether retry is safe and name the next action. Preserve only bounded diagnostics and never attach tokens, Keychain records, repository contents, or production logs to an ordinary issue.

#Reset

To repeat guided setup without uninstalling or changing the current enforcement state:

defaults delete ai.wisent.tama.desktop tama.hasCompletedSetup

Sign out from Tama to remove its Wisent session through the normal application flow. Stop supervised sessions before resetting or removing session overrides; never delete live control files while a supervisor can rewrite them.

#Uninstall

1. Stop all supervised agent sessions.
2. In Settings, choose Deactivate and confirm the decision dialog.
3. Confirm Posture shows the disabled-hooks alert and the privileged backend reports Not registered. If macOS still shows an approval item, complete its removal in System Settings before continuing.
4. Sign out and quit Tama.
5. Remove ~/Applications/Tama.app.
6. Preserve ~/Library/Application Support/Tama until rollback or incident recovery is no longer needed. It contains disabled-state and restoration evidence, not an active background service.
7. After confirming no managed dispatcher, supervisor, daemon, or Network Extension is active, the authorized operator may archive and remove Tama Application Support and dormant Tama-owned source files named by hooks-runtime/installed.json.

#Next steps

After first success:

• start with the read-only commands in ../examples/getting-started/status.sh, then choose only the script matching the intended operation;
• inspect hook purpose and side effects in Hooks;
• review expiring justification records;
• scan a repository read-only;
• learn emergency recovery before starting critical agent work;
• read operations.md before changing versions or diagnosing partial installation.