Profiles, installer and the /profile switch
This page covers how a profile becomes a working pi configuration. It describes what a profile contains, how the installer (packages/core/install.ts) turns one into settings.json entries, an install marker and a firewall config, how it chooses and migrates the kit source, how operator overrides and firewall settings are validated before anything is written, and how the in-TUI /profile command switches profiles all-or-nothing. The diagrams show the state map, one installer run, the transformations from a profile to each artefact, source and channel selection, and the /profile round trip.
A profile is a JSON file under packages/kit/profiles/ that selects which extensions load, which kit skills and prompt templates are hidden, and which tool-firewall policy and default mode apply. The installer is the single writer. It wraps pi install, narrows the kit's entry in settings.json to the resolved profile set, records a state marker and writes the firewall config. It records operator drift into overrides.json only under --capture-overrides (and automatically when it migrates off a retired source), and only when the installed entry has drifted from the marker's profile and no overrides exist yet. Unless it is the fast --settings-only path, a local checkout first passes the verify.ts consistency gate. Overrides and firewall settings are validated before the first write and fail closed, and a --settings-only run restores every file it may have touched if it does not finish.
The in-TUI /profile command in packages/extensions/src/session-helpers/index.ts is a front end for that. It locates the kit checkout, picks a profile (accepting the engagement alias for engagement), and re-invokes the installer in --settings-only mode inside a transaction: it snapshots every file a switch can change, runs the installer, judges the result by the files on disk, rolls back on any failure, and only then reloads so pi re-reads its settings without a restart. Operator customisations live in overrides.json and are applied on top of every profile, so a profile switch never silently undoes a hand-made change.
The installer writes settings.json and the install marker to the scope chosen by --scope (global to ~/.pi/agent, project to <cwd>/.pi). The other side files (pi-kit/overrides.json, pi-kit/firewall.json and the .env scaffold) stay in the global agent directory.
Component and state map
This is the whole subsystem at a glance: the inputs the installer reads (profiles, sources.json and distribution.json), the runtime it drives (pi), and the on-disk state it owns. State normally lives in the agent directory (settings.json, the install marker .pi-kit.json, pi-kit/overrides.json and pi-kit/firewall.json, plus a scaffolded .env) under PI_CODING_AGENT_DIR (default ~/.pi/agent). A project install instead puts settings.json and the marker under <cwd>/.pi/, and the other side files stay in the agent directory.
flowchart LR
Profiles["packages/kit/profiles: profile JSON files"]
Sources["packages/core/sources.json"]
Dist["packages/core/distribution.json"]
Installer["packages/core/install.ts"]
ResolveLib["lib/resolve.ts"]
SettingsLib["lib/settings.ts"]
ProfilesLib["lib/profiles.ts"]
DistLib["lib/distribution.ts"]
PathsLib["lib/paths.ts"]
Verify["verify.ts gate"]
PiCli["pi CLI"]
subgraph state["State: agent directory, default ~/.pi/agent"]
Settings["settings.json packages entry"]
Marker[".pi-kit.json install marker"]
Overrides["pi-kit/overrides.json"]
Firewall["pi-kit/firewall.json"]
EnvFile[".env scaffold"]
end
Profiles --> Installer
Sources --> Installer
Dist --> DistLib
ResolveLib --> Installer
SettingsLib --> Installer
ProfilesLib --> Installer
DistLib --> Installer
PathsLib --> Installer
Installer -->|"local checkout only"| Verify
Installer --> PiCli
PiCli --> Settings
Installer --> Settings
Installer --> Marker
Installer --> Overrides
Installer --> Firewall
Installer --> EnvFile
Overrides -.-> Installer
The installer parses these flags on process.argv.slice(2):
| Flag | Default | Notes |
|---|---|---|
--profile <name> |
balanced |
A profile that was renamed or merged (quick, autonomous; the table is RENAMED_PROFILES in packages/core/shared/profile-names.ts) exits 1 with a message naming its replacement; there are no aliases (tests/profile-rename-smoke.ts). --surface lite is a deprecated alias for --profile lite; any other --surface exits 1. |
--only <a,b> |
null | Comma-split and trimmed. Any requiredProfileExtensions member (packages/core/distribution.json) it leaves out is added back with a WARN (tests/install-marker-smoke.ts). |
--all |
false | Every in-repo, vendor and external name; the package is not narrowed. |
--scope <global\|project> |
global |
Project settings live at <cwd>/.pi/settings.json. |
--mode <local\|git\|npm> |
see below | local registers WORKSPACE_ROOT; git a source of Luna's repository; npm npm:@satunix/pi-system[@channel]. |
--channel <latest\|next\|trunk\|X.Y.Z> |
see below | Validated against that grammar (X.Y.Z may carry a prerelease suffix such as 0.2.4-beta.0); exits 1 otherwise. |
--git-ref <ref> |
null | Git only: register an arbitrary ref (main means the next channel). Implies --mode git. |
--dry-run |
false | Print actions without writing. |
--uninstall |
false | Delegates to uninstall.ts (removes Luna and the companions recorded in the marker) and exits with its status. |
--no-externals |
false | Skip companion external packages. |
--settings-only |
false | Fast path used by /profile; skips the verify gate, skips re-registration only when the kit source is already registered, and restores every file it touched if the run does not finish. |
--capture-overrides |
false | Capture settings drift into overrides.json; alone, exits after capture. |
--no-migrate |
false | Passed by /profile: exits 1 with nothing changed instead of moving Luna off a retired or previous source (tests/distribution-smoke.ts). |
--help / -h |
false | Print the usage line to stdout and exit 0 before any install work (tests/install-marker-smoke.ts). |
Any other argument, or a value flag with no value or followed by another -- flag, exits 1 with the usage line before anything else runs (tests/install-marker-smoke.ts).
--yes appears in the usage comment and is passed by /profile, but install.ts only forwards it to uninstall.ts; otherwise it is a no-op.
uninstall.ts validates its own arguments the same way: --scope must be global or project, and an unknown argument or a value flag with no value exits 1 with its usage line before it reads any marker or runs pi remove (tests/install-marker-smoke.ts).
Mode. An explicit --mode wins. Otherwise, when the installer runs from a copy pi installed itself (its path is under <agent dir>/git/ or .pi/git/, or contains node_modules), it keeps that delivery (git or npm), so /profile, /update and the first-run auto-profile never register pi's clone as a local checkout. From a git checkout it is local, unless --channel or --git-ref is given, which means "install the released Luna" with the configured delivery (packages/core/distribution.json delivery, git by default, overridden by PI_KIT_DELIVERY). Anywhere else it is the configured delivery.
Channel and source. Without --channel, a registered kit entry of the same delivery is kept as it is, with the channel recorded in the marker for that exact source (or, for git, inferred: no ref is next, a v<semver> tag is latest, any other ref is its own channel). With --channel, or when nothing is registered (default latest):
- git:
nextis the unpinned repository (pi follows its default branch),trunkis<source>@<git.trunkBranch>(the integration branch head, a canary that is never the default),X.Y.Zis<source>@vX.Y.Z, andlatestis the newest release tag found withgit ls-remote --tags(the newest stable one once a stable release exists, otherwise the newest prerelease).latesttherefore needs a release tag: the installer exits 1 when the repository has none or cannot be reached, and--channel nextfollowsmaininstead.--git-refbypasses channel selection:mainmeansnext, and any other ref is registered as<source>@<ref>. The base source isPI_SYSTEM_GIT_SOURCE(ignored, with a warning, when it names a retired source), else the registered git entry (keeping the user's HTTPS or SSH form), elsegit.sourceindistribution.json, which isgit:github.com/SATUNIX/luna. - npm:
latestis the barenpm:@satunix/pi-system, anything elsenpm:@satunix/pi-system@<channel>; with nothing registered and no--channel, a running copy whose version is anextsnapshot picksnext.
Retired private sources. distribution.json lists git.legacySources, retired private GitLab sources. A kit registered from one is never reused and never reconnected to. The installer registers the public source instead, on the channel the install was following: next stays next, a release or a pin becomes latest because a private tag does not exist publicly, and an explicit --channel wins. Before anything is replaced it captures the old entry's hand edits (extensions added or removed, skill and prompt exclusions) into overrides.json, unless overrides already exist. It then runs pi remove for the old registration (or, if that fails, drops its settings entry) and removes every other copy of Luna. A PI_SYSTEM_GIT_SOURCE that still names a retired source is ignored and reported.
flowchart TD
M{"delivery mode"}
L["local: the source is the checkout path, no channel"]
N["npm: keep the registered entry and its channel, else latest or next (or trunk)"]
G["git: gitKitSource"]
REG{"a kit git entry is registered?"}
LEG["retired private source: migrate to the public source, capture hand edits, pi remove the old entry"]
KEEP["keep the entry and its recorded channel"]
CH{"channel"}
NEXT["next: the unpinned repository"]
TRUNK["trunk: the integration branch head (canary)"]
PIN["X.Y.Z: the source at vX.Y.Z"]
LATEST["latest: newest release tag from git ls-remote, exit 1 when there is none"]
M -->|local| L
M -->|npm| N
M -->|git| G
G --> REG
REG -->|"a retired source"| LEG
REG -->|"a non-retired entry and no --channel"| KEEP
REG -->|"none, or --channel given"| CH
LEG -->|"next stays next, anything else becomes latest, unless --channel is given"| CH
CH -->|next| NEXT
CH -->|trunk| TRUNK
CH -->|"X.Y.Z"| PIN
CH -->|latest| LATEST
--capture-overrides runs as a pre-pass before anything is rewritten: it reads the marker, finds the kit entry (the retired entry when migrating), compares the settings entry against the marker's extension list via captureDrift, and writes pi-kit/overrides.json unless dry-run or overrides already exist. With no explicit profile, --only or --all it then exits 0.
Installer run, end to end
A typical node packages/core/install.ts --profile balanced execution runs, in order: argument validation; the uninstall short-circuit; under --settings-only, the snapshot of every file it may write; the choice of kit source and channel; the capture pre-pass; validation of the overrides and the firewall settings; preflight (pi, plus git outside npm mode); the verify.ts gate (local mode only, and not for --settings-only: a release and main were checked in CI, and the gate would check this copy rather than the one being registered); pi install (skipped under --settings-only when exactly this source is already registered); the package narrowing; removal of every other kit registration; companion externals; the .env scaffold; the firewall config; and finally the marker write.
sequenceDiagram
participant Op as Operator
participant Inst as install.ts
participant Files as agent directory files
participant Verify as verify.ts
participant Pi as pi CLI
participant Settings as settings.json
participant Sources as sources.json
Op->>Inst: node packages/core/install.ts --profile balanced
opt settings-only
Inst->>Files: snapshot settings, marker, firewall, overrides and .env
end
Inst->>Inst: choose the kit source and channel
opt capture-overrides, or migrating off a retired source
Inst->>Files: write overrides.json from settings drift
end
Inst->>Files: read and validate overrides.json and firewall.json
Files-->>Inst: valid, or exit 1 and nothing written
Inst->>Inst: preflight git and pi
opt local checkout and not settings-only
Inst->>Verify: run the verify gate
Verify-->>Inst: pass, or exit 1
end
Inst->>Pi: pi install kitSource with the scope flag
Pi->>Settings: write the package entry
Inst->>Settings: mergePackageBlock narrows extensions, skills and prompts
opt migrating off a retired source
Inst->>Pi: pi remove the retired registration
end
Inst->>Settings: removeOtherKitEntries
Inst->>Sources: read the reference companions
Inst->>Pi: pi install each unregistered companion
Inst->>Files: scaffold .env if absent
alt --scope global
Inst->>Files: write firewall.json and security.json from the profile
else --scope project
Inst-->>Op: WARN where the profile's gate differs from the global files
end
Inst->>Files: write the .pi-kit.json marker
Inst-->>Op: Done, run /reload
Note over Inst,Files: a failed step under settings-only restores the snapshots
The kit source is WORKSPACE_ROOT for local mode, or the git or npm source chosen above. pi install registers the full wildcard package; mergePackageBlock then narrows it so the profile actually controls what loads. Under --all nothing is narrowed. When a real profile is loaded the installer also computes skill and prompt filters; --only and --all pass no filters and leave whatever skill and prompt keys the entry already has. After registering, removeOtherKitEntries removes every other registration of Luna (another checkout, another delivery, or a legacy dist/pi-kit-* export or split package): exactly one may remain, or shared skill, prompt, extension and theme names collide. When a companion's registered spec differs from Luna's pin, it is reinstalled at the pin. Companion externals are the mode: "reference" entries in sources.json whose provides intersect the selected set; pi-lean-ctx is skipped when leanCtxBinaryAvailable() is false. The .env file is scaffolded from packages/core/.env.example only if absent. It is created with mode 0600 because it holds API keys, and an existing .env keeps its bytes and mode (tests/install-marker-smoke.ts). The installer reads PI_SYSTEM_GIT_SOURCE, PI_KIT_DELIVERY, PI_CODING_AGENT_DIR (through the settings helpers), PI_KIT_FIREWALL_CONFIG (through firewallConfigPath) and PI_LEAN_CTX_BIN or LEAN_CTX_BIN; it writes no environment variables, only the .env file.
Validation and rollback
Safety-critical configuration is validated before the first write, and an error stops the run with exit 1 and nothing changed.
- Overrides. Only a profile install applies overrides, so only then can they stop the run. An
overrides.jsonthat exists but cannot be read, is not valid JSON, or is not a JSON object is refused, because it may hold the removal of a protection the installer cannot see. Removing a mandatory protection extension (tool-firewall,secret-guardorprotected-paths) inextensions.removeis refused outright. Removing any other required extension (delegation-guard,effortorsession-helpers, fromrequiredProfileExtensions) is ignored with a warning, so it still loads (tests/profile-safety-smoke.ts). Names that no longer exist in Luna (a renamed or removed extension, skill or prompt) are dropped with a warning, so a stale override does not fail the whole switch. - Firewall.
checkFirewallConfigruns first: a profile whosefirewallblock is not an object or names an unknown policy (codingorengagement) or mode (autoormanual), and an existingfirewall.jsonthat names an unknown policy or mode, cannot be read, or is not a JSON object, all stop the run. Nothing falls back to a default, so a typo cannot loosen the gate. Under--scope global, writingfirewall.jsonandsecurity.jsonat the end is fail-closed as well. Both files are machine-global, so a--scope projectinstall never writes them: it leaves them byte-identical and prints aWARNnaming the global file and the--scope globalcommand when the profile wants a different firewall mode, policy or securityLevel (tests/install-marker-smoke.ts). - Rollback. Under
--settings-onlythe installer snapshotssettings.json, the marker,firewall.json,security.json,overrides.json,pi-kit/profile-settings.jsonand.envfirst. Any exit that is not a clean finish (a failed step, an uncaught exception,SIGINT,SIGTERMorSIGHUP) restores every one of them, so the configuration is either the old one or the complete new one. The run counts as finished only once the marker, its last write, is on disk.
How a profile becomes settings, overrides, marker and firewall
This diagram traces the transformations from a profile definition to each artefact. Overrides are validated first (readOverridesChecked and reconcileOverrides). Extensions flow through applyExtensionOverrides and resolveProfile into the settings entry; skill and prompt exclusions flow through excludedSkills and excludedPrompts; the firewall block is validated by checkFirewallConfig and flows through firewallConfigFor; and the marker records the profile, selected extensions, scope, mode, ref and channel.
flowchart LR
Profile["profile definition: include, firewall, skills, prompts"]
OverridesIn["overrides.json operator edits"]
OvCheck["readOverridesChecked and reconcileOverrides: fail closed, drop stale names"]
FwCheck["checkFirewallConfig: unknown policy or mode, unreadable file, exit 1"]
ApplyExt["applyExtensionOverrides"]
ApplySkill["excludedSkills and excludedPrompts"]
Selected["selected extension set"]
ResolveProf["resolveProfile"]
Merge["mergePackageBlock"]
Entry["settings packages entry: extensions, skills, prompts"]
FirewallFor["firewallConfigFor"]
FwFile["pi-kit/firewall.json: mode, policy, source"]
MarkerData["marker: profile, extensions, overrides, scope, mode, ref, channel"]
OverridesIn --> OvCheck
Profile --> ApplyExt
OvCheck --> ApplyExt
Profile --> ApplySkill
OvCheck --> ApplySkill
ApplyExt --> Selected
Selected --> ResolveProf
ResolveProf --> Merge
ApplySkill --> Merge
Merge --> Entry
Profile --> FwCheck
FwCheck --> FirewallFor
FirewallFor --> FwFile
Selected --> MarkerData
OvCheck --> MarkerData
Profile --> MarkerData
settings.json. The profile filters live inside the kit's entry in settings.packages[], never as a top-level key. mergePackageBlock converts that entry to object form:
sourceis unchanged (local paths are stored relative to the settings directory).extensionsare relative paths, exactlypackages/extensions/src/<name>/index.tsorpackages/extensions/third_party/<name>/index.ts; external companions are excluded because they are separate package entries.skillsare!packages/kit/skills/<name>/SKILL.mdpatterns; the key is deleted when the list is empty.promptsare!packages/kit/prompts/<name>.mdpatterns; same set and delete rule.- All other keys, such as
themes, are preserved.
Writes go through a lock file <settingsPath>.pi-kit.lock plus tmp-and-rename, so pi never observes a half-written file. A settings.json that exists but does not parse is never rewritten.
overrides.json lives at <agentDir>/pi-kit/overrides.json. The installer writes it under --capture-overrides and when it migrates off a retired source; an operator can also edit it. Its normalised shape is:
{
"extensions": { "add": ["name"], "remove": ["name"] },
"skills": { "exclude": ["name"], "include": ["name"] },
"prompts": { "exclude": ["name"], "include": ["name"] }
}
Extensions are applied remove-then-append (add); skills and prompts use excludedSkills and excludedPrompts, where an include entry wins over an exclusion (and over a profile's only allowlist). The file is written pretty with a trailing newline via tmp and rename.
firewall.json lives at <agentDir>/pi-kit/firewall.json (overridable with PI_KIT_FIREWALL_CONFIG) and is written by writeFirewallConfig:
{ "mode": "auto", "policy": "coding", "source": "profile" }
policy always follows the profile (engagement only when the profile says so, otherwise coding). mode follows the profile too, unless the existing file has source: "user" with the same policy and a valid mode; then the operator's /auto choice is kept with source: "user". Other keys such as judgeModel, learn, knownHosts and untrustedHosts are always preserved.
The install marker is <globalAgentDir()>/.pi-kit.json for a global install and <cwd>/.pi/.pi-kit.json for a --scope project install, so a project install never clobbers the global marker (and vice versa). Runtime readers that resolve install state (/update, /profile, /console, the standalone web-ui installer) follow the same precedence as uninstall.ts: a project marker in the current directory wins when it exists, otherwise the global marker is used. It is written with writeSettingsAtomic. Its exact keys are kitSource, profile, extensions, overrides, scope, mode, ref, channel, companions and installedAt.
profileis"all"for--all,"custom"for--only, and the canonical profile name otherwise.overridesisnullwhen empty.refis the git ref of the registered source (null fornextand outside git mode).channelislatest,next,trunk(the opt-in integration-branch canary), a pinned version or (in git mode) a raw ref, and null for a local checkout.companionsis the array of companionsourcestrings this install is responsible for. Only the companions this run installs, or reinstalls at Luna's pin, are newly recorded, and companions already recorded by a previous install are carried over; a companion the operator registered at Luna's pin before the run is left out, so uninstall leaves it registered (tests/install-marker-smoke.ts). A recorded companion stays tracked untilpi removeactually removes it. A later install that no longer selects it (including--no-externals) does not drop it. With no prior marker,--no-externalsrecords[]. Each entry is exactly the stringuninstall.tspasses topi remove. A companion skipped for a missing prerequisite (onlypi-lean-ctxwithout its CLI) is not newly recorded by that run, but one recorded by an earlier install is still carried over.
The marker is the installer's last write, which is why /profile can use a fresh installedAt as evidence that the installer finished.
The per-profile firewall and exclusion data is fixed in the profile JSON:
| Profile | firewall mode | firewall policy | skills/prompts exclusions |
|---|---|---|---|
| balanced | manual | coding | yes |
| long-horizon | auto | coding | yes |
| self-improving | auto | coding | yes, plus experimental: true |
| engagement | manual | engagement | none: the profile has no skills or prompts keys |
| lite | manual | coding | allowlists: skills.only (12 skills) and prompts.only (the four code-* templates) |
The three other non-engagement profiles share the same exclusions: skills.excludeCategories is ["engagement","mcp-governance","evidence-reporting","maintainer"], skills.exclude is ["engagement-conductor","dynamic-agent-synthesis"], and prompts.exclude lists golden-path-engagement, engagement-action-card, engagement-compact, engagement-plan, engagement-report-finding, engagement-triage-burp, engagement-verify-evidence, mcp-action-review, report-export-review, tool-policy-onboarding and hypothesis-lifecycle. Because engagement carries no skill or prompt keys, no skill or prompt exclusions are applied for it. --only and --all likewise leave existing skill and prompt keys untouched.
The marker's companions array closes the loop: packages/core/uninstall.ts reads it and removes each recorded source with pi remove, so a plain uninstall.ts run does not leave the companions behind.
The /profile round trip
/profile is the TUI front end. It resolves the kit root, reads the actually loaded set back out of settings.json, offers to capture drift, and then switches all-or-nothing. transactionalSwitch in packages/extensions/src/session-helpers/profile-switch.ts snapshots every file a switch can change, runs the installer with --settings-only, checks the result against the files on disk, and restores the snapshot byte for byte on any failure. It reloads only after a verified switch. A renamed profile typed to /profile is refused with the same message from RENAMED_PROFILES; the install marker's stored profile is migrated one way on read (migrateStoredProfile) and rewritten by the next install.
sequenceDiagram
participant U as User
participant SH as session-helpers profile command
participant Kit as Kit root resolution
participant TS as transactionalSwitch
participant Inst as install.ts settings-only
participant Files as settings, marker, firewall, overrides and .env
participant Pi as pi
U->>SH: /profile engagement
SH->>SH: reject a renamed name, check the profile and its firewall block
SH->>Kit: findKitRoot then resolveKitLayout
SH->>Files: loadedKitExtensions and matchProfile against the profile files
SH->>U: confirm capture when drift is detected
SH->>TS: runSwitch
TS->>Files: snapshot every file the switch can change
TS->>Inst: node install.ts --profile engagement --yes --settings-only
Inst->>Files: rewrite settings, firewall and marker
Inst-->>TS: exit code and output
TS->>Files: verifySwitch: marker, settings entry and firewall agree with the profile
alt installer failed, was killed or did not finish, or verification found a problem
TS->>Files: restore the snapshot byte for byte
TS-->>SH: failure message, nothing changed
SH-->>U: error notification, no reload
else consistent
TS-->>SH: announce the switch
SH-->>U: switched to engagement
TS->>Pi: waitForIdle then reload
opt the reload fails
TS->>Files: restore the snapshot
TS->>Pi: reload the old configuration
end
end
Judging by the files. pi.exec() reports a signal-killed child as exit code 0, so a zero exit code is not evidence that the installer finished. The switch counts as failed if the installer throws, is killed (it has a 120 s timeout), exits non-zero, or exits 0 after printing output that lacks its [install] Done. line. Otherwise verifySwitch checks the files:
- the marker parses as an object, names the requested profile and scope, was stamped after the switch started, and lists every expected extension;
- the kit entry in
settings.jsonis filtered, its extension list equals the profile's (same names, same order, overrides applied) and every listed extension exists in Luna; - for a global switch only,
firewall.jsonparses as an object, its policy is known and matches the profile, and its mode is known and matches the profile unless the operator set it (source: "user"). A project-scoped switch is not held tofirewall.json, because a project install leaves the global gate files alone (tests/profile-transaction-smoke.ts).
The files snapshotted are switchFiles(): the global and the project settings.json and marker, firewall.json, security.json, overrides.json, pi-kit/profile-settings.json (the record of the pi settings a profile's settings block owns, which must roll back with settings.json) and .env, so a global switch cannot disturb a project and the reverse. Leftover lock and temporary files an interrupted installer leaves beside them are removed. If a file cannot be restored, the original bytes are saved to a backup directory and named in the error. Before any of this, runSwitch refuses a profile whose firewall block names an unknown policy or mode. The same transaction runs the first-run auto-profile: a kit registered unfiltered (a bare pi install of the git or npm source) gets the balanced profile at the first interactive session (PI_KIT_AUTO_PROFILE=0 turns this off, a profile name picks another), applied without a reload and with a notice to run /reload.
Command surface: no argument opens an interactive ui.select picker in the TUI, or prints profile: usage: /profile <balanced|lite|long-horizon|engagement|self-improving> (or /profile status) in a non-UI context. /profile <name> switches. Arguments are validated before anything can change: one word or nothing, and a known profile name. /profile list and /profile --list print the current profile, the settings path, the profile list and, when the file exists, an overrides line. /profile status prints the effective configuration (profile, install mode, channel and source, the loaded extensions with a warning for a missing tool-firewall or protected-paths, the firewall policy and mode, the compaction state, overrides and companions), then extra vs <closest> and missing vs <closest> drift lines when a kit entry is loaded, no profile matches exactly and a closest profile exists, then the profile list. getArgumentCompletions offers status, list and every profile name.
Kit root resolution is PI_KIT_ROOT first (validated by resolveKitLayout; a value that is not a kit is an error, not a fall-through), then the marker's kitSource when it is an absolute path that resolves outside the workspace (the enclosing git work tree, else the session directory) and whose package.json names a Luna package (@satunix/pi-system or @satunix/luna) (any other path is ignored with a warning, since a project marker is repository content; see the Security model), then the module's own location (four levels up in the monorepo layout, two in the legacy flat one). resolveKitLayout accepts the monorepo layout (packages/core/install.ts plus packages/kit/profiles/) or the legacy flat layout (kit/install.mjs plus profiles/). The published npm package keeps the monorepo layout, so /profile works the same for npm installs; if no layout is found it errors and tells the operator to set PI_KIT_ROOT.
Apart from restoring a snapshot after a failure, /profile writes no file itself; the installer does. It spawns pi.exec(nodeBinary(), args, { cwd, timeout: 120_000 }) with cwd set to the project directory for a project-scoped switch (when <cwd>/.pi/settings.json contains a Luna package entry (@satunix/pi-system or @satunix/luna, or a path to the checkout), filtered or unfiltered, or the marker says scope: project) and to layout.root otherwise. install.ts derives a project install's settings.json and marker paths from process.cwd(), so a project-scoped switch must run in the project: running it in the kit root would write into the kit checkout and never update the user's project. It passes args = [layout.installer, "--profile", target, "--yes", "--settings-only"], adding --capture-overrides when capturing, --scope project when the switch is project-scoped (or --scope global only when the marker says scope: global), and --mode git or --mode npm when the marker records that delivery (never a ref: the installer keeps the registered source and its recorded channel).
Helpers: loadedKitExtensions finds the kit entry (a local path equal to the kit root by realpath, or the npm or git package when the kit root is pi's installed copy), parses extension patterns matching (?:src|third_party)/([^/]+)/index.ts, and returns the names, or null for a missing entry or a string or unfiltered entry. matchProfile computes exact or closest-by-symmetric-difference against profileKitExtensions (the profile include plus overrides, filtered to in-repo names); when two profiles have the same set, the marker's profile wins the tie. The displayed "current" prefers the actually loaded set over the marker; with no readable entry it falls back to marker.profile and labels it "unfiltered package". listProfiles does not apply the engagement alias: it lists the JSON files as they are. Cancelling the picker, or re-selecting the current profile, does nothing.
verify.ts profile and source checks
The verify gate that runs before a normal local install (packages/core/verify.ts) never reads settings.json. It checks the consistency of profiles against extension manifests and sources.json:
- Forward check. Every profile-included name must have an
extension.jsonmanifest or appear insources.jsonexternal[].providesor name, elseprofile include "..." has no extension.json and no sources.json entry. - Bidirectional manifest check. Each manifest's
meta.profilesmust exactly equal the actual membership derived fromprofiles/*.json, elseprofile metadata drift for "...". - Orphan check. A
stableorbetamanifest with zero memberships fails. - External cross-check. Each
sources.jsonentry'sprofilesmust equal the membership for every name it provides, elseexternal source profile drift. - Stub and TODO quarantine. A
stuborexperimentalextension shipping in a non-experimental profile fails, as does a(stub)or: TODOmarker in those extensions.
The rest of verify covers TypeScript, the extension.json schema, name collisions, self-containment and the hooks manifest, the context-sieve injection monopoly, the firewall starter policy and security pattern parity, and catalogue, notices and docs drift. Profile filtering correctness itself, and the transactional switch, are exercised by packages/core/profile-check.ts, tests/profile-command-smoke.ts, tests/profile-transaction-smoke.ts and tests/profile-safety-smoke.ts, not by verify.ts.
sources.json and environment
packages/core/sources.json has one external array of entries with name, mode (reference or bundle), source, optional entry, provides, profiles, review, and optional optional. The installer reads it to extend allExtensionNames() for --all, to pick reference companions whose provides intersect the selection, and lib/resolve.ts resolves any name not found in src/ or third_party/ as avenue: "external". Verify cross-checks each entry's profiles against actual membership. External companions are installed as their own separate settings.packages[] entries and never appear inside the kit entry's extensions.
Environment variables that affect this subsystem:
PI_CODING_AGENT_DIR: agent and config directory for the globalsettings.json,.pi-kit.json,.envandpi-kit/(a project-scope install keeps itssettings.jsonand marker under<cwd>/.pi/instead).PI_KIT_DELIVERY:gitornpm, overridingdeliveryindistribution.json.PI_SYSTEM_GIT_SOURCE: installer git source override; ignored, with a warning, when it names a retired private source.PI_KIT_FIREWALL_CONFIG:firewall.jsonpath override, used by both the installer and the runtime.PI_KIT_FIREWALL_PROFILE: runtime policy override in tool-firewall; not read by the installer.PI_KIT_AUTO_MODE,PI_KIT_AUTO_MODE_STATE_DIR: runtime mode override and legacy state path; not the installer.PI_KIT_ROOT: pins the kit checkout/profiledrives.PI_KIT_AUTO_PROFILE:0,off,falseornodisables the first-run auto-profile; a profile name selects that profile instead ofbalanced.PI_KIT_LEAN_CTX: session-helpers lean-ctx preflight toggle.PI_LEAN_CTX_BINorLEAN_CTX_BIN: lean-ctx binary path, used as the installer companion-skip gate and by preflight.PI_KIT_FIREWALL_POLICY,PI_KIT_FIREWALL_AUDIT_LOG,PI_KIT_FIREWALL_FEEDBACK,PI_KIT_FIREWALL_SESSIONS_DIR,PI_KIT_FIREWALL_APPROVALS: runtime firewall files, not the installer.PI_KIT_COMPACT_THRESHOLD_TOKENS: trigger-compact and session-helpers, not the installer.
Source files
- Installer entry point, flag parsing, source and channel selection, ordered install steps, whole-run rollback:
packages/core/install.ts - Delivery and source rules (
readDistribution,parseGitSource,isLegacyGitSource,gitSourceFor,releaseTags,latestRelease,channelOfGitSource):packages/core/lib/distribution.ts, with the settings inpackages/core/distribution.json - Profile definitions, firewall block and include lists:
packages/kit/profiles/balanced.json,packages/kit/profiles/long-horizon.json,packages/kit/profiles/self-improving.json,packages/kit/profiles/engagement.json,packages/kit/profiles/lite.json applyExtensionOverrides,readOverridesChecked,reconcileOverrides,excludedSkillsandexcludedPrompts,skillFilterPatternsandpromptFilterPatterns,captureDrift,readOverridesandwriteOverrides,firewallConfigPath,checkFirewallConfig,firewallConfigForandwriteFirewallConfig,snapshotFilesandrestoreSnapshots:packages/core/lib/profiles.tsglobalAgentDir,globalSettingsPath,mergePackageBlock,removeOtherKitEntries,isKitNpmSource,isKitGitSource,findPackageEntry,writeSettingsAtomic,updateSettings,withSettingsLock,leanCtxBinaryAvailable:packages/core/lib/settings.ts- Layout constants (
WORKSPACE_ROOT,PROFILES_DIR,FIRST_PARTY_DIR,THIRD_PARTY_DIR,SOURCES_PATH,ENV_EXAMPLE) andextensionRelPath:packages/core/lib/paths.ts - Name resolution to in-repo, vendor or external avenue:
packages/core/lib/resolve.ts /profilecommand,findKitRoot,resolveKitLayout,loadedKitExtensions,matchProfile,profileKitExtensions,listProfiles,runSwitch, the first-run auto-profile:packages/extensions/src/session-helpers/index.ts- Snapshot, installer run,
verifySwitchand rollback for a switch:packages/extensions/src/session-helpers/profile-switch.ts - Consistency gate for profiles, manifests and sources:
packages/core/verify.ts - External package catalogue and its schema:
packages/core/sources.json,packages/core/schema/sources.schema.json - Profile filtering replay and smoke tests:
packages/core/profile-check.ts,tests/profile-command-smoke.ts,tests/profile-transaction-smoke.ts,tests/profile-safety-smoke.ts,tests/distribution-smoke.ts - Scanner that reads the
marker.companionskey written by the installer:packages/core/uninstall.ts