Install edge cases and lifecycle details

Compatibility preflight

The standalone installer accepts macOS 11 or newer on Apple Silicon and Intel, plus x86-64 Linux with glibc 2.35 or newer. On Linux, it parses getconf GNU_LIBC_VERSION and refuses musl, an older glibc, a missing getconf, or an invalid result before download or mutation under HOME. Use a newer glibc host or build with Rust 1.95 when that preflight fails.

A set XDG_CONFIG_HOME, XDG_STATE_HOME, or XDG_DATA_HOME must be absolute. Empty or relative XDG config and state values fall back to the corresponding absolute HOME paths; an invalid data root fails closed.

Tool discovery and reload

Supported tool names are jcode, claude, codex, gemini, and opencode. Curl-bootstrap detection examines executable names on PATH only. A stale tool directory or an old managed skill does not mean the host tool is installed. With no target and a usable terminal, the installer shows all five tools, preselects only detected executables, and still permits explicitly selecting a not-found tool. It distinguishes found, not found, integration present, and needs repair; present is intentionally not called active until the downloaded binary performs authoritative preflight. If raw-key controls are unavailable, the same choices use a numbered line prompt. With no terminal and no explicit target, installation fails before download or mutation and prints exact rerun forms. Pass --all for unattended installation of every integration, or name a comma-separated subset such as jcode,codex.

Before download, the installer prints the release asset, checksum source, command, optional alias, document directory, and every selected integration path. Interactive use asks for one final Enter confirmation. Every long phase prints a durable name before work starts and an ok line on completion; non-terminal explicit-target installs never use cursor rewrites or animations.

The default SKILL.md remains the canonical execution and safety contract. Installation renders a profile for each selected tool with the same embedded managed-binary path and tool-specific routing and execution guidance. Claude also receives an always-loaded user rule at ~/.claude/rules/azdaja.md and a managed hook plugin inside its skill directory. For complete-coverage work on a large input, the hook allows metadata checks and one structural sample of up to 10 lines and 64 KiB only through absolute trusted /usr/bin/... or /bin/... commands with literal, non-expanding paths, then blocks broader native Read, Grep, or Bash access until Skill(azdaja) succeeds. Small inputs and bounded excerpts stay unforced. The installer owns only the exact rule symlink and managed plugin files, refuses foreign entries, checks all surfaces in doctor claude, and removes only owned content. Restart Claude after install. Codex CLI 0.149 discovers Agent Skills from $HOME/.agents/skills, project/upward .agents/skills, project/upward .codex/skills from both trusted and untrusted project layers, system/admin roots, and $CODEX_HOME/skills when CODEX_HOME is set. CODEX_HOME must be absolute and isolates Codex config/auth, but it does not move the normal Azdaja compatibility profile away from $HOME/.agents/skills/azdaja. Codex skill activation is per turn: $azdaja, a plain skill-name request, or a task matching the narrow description can load the skill for that turn, while passive discovery, a repository name, and mere mentions are non-triggers. The managed Codex profile includes agents/openai.yaml with interface.display_name, interface.short_description, interface.default_prompt, and policy.allow_implicit_invocation: true, defaults to the standard conversational lane, and reserves the strict A/B benchmark/audit lane for explicit exact-schema requests. Nested Codex model calls are ephemeral and JSONL-metered, explicitly pin model_reasoning_effort=low, ignore user config and rules, disable skills, shell, image, web, and multi-agent tools, strip inherited provider credentials through the doctor-validated {isolated_env} contract, and run from a fresh private directory outside project roots. Nested calls use the normal stored Codex login under CODEX_HOME; run codex login instead of relying only on an API-key environment variable. Reinstall automatically migrates only byte-exact legacy managed Codex configs; customized configs stay untouched, while doctor codex rejects any Codex command that lacks the isolation contract. Restart Codex, or start a fresh codex exec invocation, after install or reinstall. doctor codex checks only files and effective user config, never providers; it rejects [skills] include_instructions=false, a managed skill disabled by [[skills.config]], and any visible same-name duplicate unless that duplicate's exact absolute SKILL.md path is disabled by the user $CODEX_HOME/config.toml. OpenCode discovers Azdaja through its native skill tool. Its execution trigger routes only exhaustive semantic judgment over one large input and explicitly excludes repository audits, code navigation, structural searches, bounded excerpts, and small deterministic work; explicit requests to use Azdaja or confirm its availability remain awareness triggers. The standard lane uses deterministic reduction plus at most one semantic pass and returns to normal conversation; the A/B adjudication and fail-closed contract remain available only for explicit audit or benchmark work. OpenCode also searches global and project/upward Claude- and Agent Skills-compatible locations, so the managed Codex compatibility profile carries the same narrow standard/strict contract and doctor opencode rejects stale or foreign same-name profiles that could shadow the dedicated OpenCode copy. No OpenCode plugin blocks native tools. Reinstall every reported compatibility profile after upgrading. Reinstall a tool to reset its managed profile from the default contract.

JCODE_HOME is authoritative when set and must be an absolute path. The generated Jcode profile says MUST invoke when a user names Azdaja, asks whether it is available or how it works, names the az virtual-memory tool, or requests complete semantic work beyond one safe context. Installation also adds one exact delimited block to JCODE_HOME/config.toml. Its pre_tool hook allows bounded narrow reads, Git control, builds, and tests, while broad repository or multi-file inspection returns a challenged solo --repo . command. Replace <user task> with the current request, run that command once, continue from its answer, and do not retry the blocked broad read. Azdaja configures only synchronous pre_tool; detached observer hooks remain untouched. If hooks.pre_tool_timeout_ms is present it must be at least 1000 ms. doctor jcode also rejects a JCODE_HOOK_PRE_TOOL override or an invalid/too-low JCODE_HOOK_PRE_TOOL_TIMEOUT_MS, because those environment values take precedence over the file. The installer never overwrites foreign hook values, uninstall removes only the byte-exact managed block, and a customized managed block is refused rather than guessed at. Automatic transactional Jcode config.toml mutation currently fails closed on Windows instead of using path-based rename; configure hooks.pre_tool manually there. /azdaja remains the deterministic manual skill activation path. After installation, run the exact shell-quoted managed-binary doctor command printed by the installer, then reload an existing Jcode registry with skill_manage reload_all or /skills → Reload all, or start a fresh tool session.

doctor NAME checks that tool's managed files on disk without invoking a model. An unqualified doctor runs the configured route canary.

Command names, paths, and configuration

The curl route creates the relative az -> azdaja alias only when no az command already resolves on PATH. It never replaces a foreign command such as Azure CLI. When install reports az alias unavailable, use azdaja.

If the binary directory is off PATH, the printed next step uses its absolute shell-quoted path. Paths with spaces, Unicode, and apostrophes are supported.

Standalone configuration uses adjacent azdaja-config.toml and azdaja-config.toml.managed files. An unrelated config.toml is never changed. Explicit AZDAJA_HOME and AZDAJA_CONFIG values must be nonempty absolute paths.

Cargo route

Cargo installs the canonical binary but no short alias or tool integration. Complete setup with azdaja install for detection or azdaja install jcode,codex for an atomic subset, then run the doctor command that installation prints. Remove managed integrations before cargo uninstall azdaja.

Official v0.1.18 binaries include the optional Jev transport. Add --features typesafe to a Cargo build/install for the same capability, or omit it to exclude that transport. Supplying the configured TypeSafe environment key or attaching it with azdaja jev attach --stdin opts into automatic Jev mode on later exec and explicitly executed batches, not autonomous solo. No key means off, and [judge] enabled = false always keeps it off. Setup and doctor --caps never make provider calls. doctor jev checks only local policy and credential syntax, not provider authentication. Existing explicit false settings are preserved on upgrade. See typed judgments.

Safe removal

uninstall NAME removes that tool integration and keeps standalone files. uninstall standalone removes only curl-owned standalone surfaces and keeps tool integrations. uninstall all removes both.

Every multi-target removal validates all selected paths before deletion. Changed managed binaries or skills, unknown files, symlinks, hardlinks, incomplete ownership state, and foreign documents cause refusal before selected mutation. A user-edited integration config.toml, foreign az, and unrelated neighboring files remain untouched.

Selected files move to same-filesystem quarantine before commit. A late failure restores them; concurrent lifecycle operations serialize or fail closed. Standalone modes refuse an unmanaged Cargo executable and direct the user to the Cargo removal sequence.

Optional activation and safe removal

Installation only makes the optional integration available. It does not activate Azdaja based on a mention, repository text, or the mere presence of a hook. Choose the narrowest explicit scope for the current request, session, or repository with AZDAJA_JCODE_ACTIVATION=request, session, or repository; unset or ambiguous values leave normal host-native behavior available.

The integration is cooperative and reversible. If internal routing or a memory handoff fails, Jcode reports the actual failure and does not remove access to the host's native tools. Native Read, Grep, Bash, and equivalent tools retain ambient permissions, and Azdaja is not an OS sandbox. doctor should be used to inspect managed state before changes. uninstall removes only Jcode-owned entries and preserves foreign hooks and user-owned configuration.

Security issues belong in a private GitHub security advisory, not a public issue containing sensitive details. See SECURITY.md.