Every PMA-specific term, defined once. For asd-side terms (route, tunnel, registry, caddy-state, etc.) see
/asd/reference/glossary.
Active mode — The currently-selected ASD_ENV value. Drives container naming, volume naming, port allocation. Set via .env on the host, not toggled per-shell.
asd-pma — The git repository name for the PMA project. Source of truth for the framework code, per-service packages, just recipes, scripts.
Authentik — The bundled SSO identity provider. Every other PMA service authenticates against it. Can be replaced with an external Authentik / Keycloak / Okta — see /pma/cookbook/integrate-existing-authentik.
Authentik group — A logical user group in Authentik. Maps to roles in downstream services (e.g. admin group → Redmine administrators, ERPNext System Manager). Manage via just authentik-groups + just authentik-group-add.
Backup type — database (postgres/mariadb dump) / volume (tar of named docker volume) / workspace (tar of workspace dir) / config (env-var slice). Declared in manifest's backup.type.
Bootstrap — The first-time install flow. Reads each package's manifest, brings the service up, wires SSO, takes initial backup. Invoked via just bootstrap-local <profile> [<env>].
Classification — core (always required), enterprise (paid/heavy SaaS replacements), optional (utility). Declared in manifest. Drives default profile membership.
Container prefix — asd-${ASD_ENV}-. Every container's name starts with this. E.g. asd-dev-redmine, asd-prod-mattermost. Set in .env as CONTAINER_PREFIX.
Contract — just contract-generate produces an in-memory snapshot of every command and package. Pre-commit hooks fail on contract drift. The MCP gateway exposes the contract to AI agents.
ENV_PREFIX — Set from ASD_ENV (e.g. dev-, prod-). Prepended to tunnel hostnames so dev and prod URLs don't collide.
Framework — The generic code in scripts/, Justfile, bootstrap orchestrator. Contains NO service-specific logic. Enforced via hooks: if service == "redmine" is blocked in framework code (Golden Rule 12).
Golden Rule N — Numbered rules in CLAUDE.md codifying operational discipline. Rule 0: no ad-hoc fixes, always root cause. Rule 1: ticket first. Rule 3: use just mcp-asd. Rule 8: bootstrap-first fixes. Rule 11: recovery playbook required. Rule 13: release-run atomic. Rule 14: PR template. Rule 15: archive completed projects. Rule 17: English in new files.
Install Skill — Formal protocol (.claude/commands/install-service.md) that AI agents follow to add a new service. Phases 0-4. Ensures consistent package structure.
Lifecycle hooks — Per-package scripts in packages/<svc>/scripts/: pre_start_init.ts, post_start_init.ts, post_data_restore.sh, ensure-config.ts. The framework invokes them at the right moment in the lifecycle.
Manifest — packages/<svc>/manifest.yaml. Declares container, ports, DB, SSO, backup, health, E2E test config. Schema: /pma/reference/manifest.
MCP gateway — The claude_ai_PMA MCP server. Exposes Redmine/Zammad/n8n/email/health/logs operations to AI agents. Same surface humans get via just.
MERGE_SHA — The git commit HEAD becomes after release-run pulls. Captured in .asd/workspace/releases/<ticket>.env.
MIGRATE_SHA — alias for MERGE_SHA, occasionally in older logs.
n8n workflow — JSON file in packages/n8n/workflows/. Imported during bootstrap. PMA ships ~20 workflows for cross-service integration (Redmine → Mattermost notifications, Grafana alerts, slash commands).
Per-ticket script — releases/<ticket>-*.sh or releases/<ticket>-*.ts. Phase 3 of release-run invokes it if present. For data migrations / workflow imports / one-off ops.
Package — packages/<svc>/. Self-contained unit: manifest, compose, hooks, scripts. The framework treats each package as a black box defined by its manifest.
Plugin — In PMA context, usually refers to plugins of the underlying services (Redmine plugins, Wiki.js modules). For asd-side plugin model, see /asd/learn/07-build-a-module.
Profile — Named subset of services declared in services.yaml. minimal / development / enterprise / support / data / full. Switch via just profile set <name>.
Recovery playbook — YAML file in recovery/playbooks/. Maps symptom → detection → root cause → fix → verify. Required for every bootstrap fix per Golden Rule 11.
Release orchestrator — scripts/release/run.sh. Four phases: prepare / migrate / ticket-script / verify. Invoked via just release-run TICKET. Atomic, halt-on-failure, with just release-revert TICKET for rollback.
Release script — Per-ticket migration in releases/. Hand-curated for ticket-specific data migrations. Distinct from migrate.sh (auto-generated from diff every release).
SSO type — One of: oauth, oidc, saml, proxy, wikijs, frappe. Declared in manifest.yaml's sso.type. Drives which generic SSO flow runs during bootstrap.
State file — .asd/workspace/releases/<ticket>.env. Written at end of phase 1 of release-run. Records BASE_SHA, MERGE_SHA, SERVICES, BACKUPS. Read by release-revert.
Ticket — A Redmine issue. Every change in the project starts with one (Golden Rule 1). Format: #NNNN in commits and PR titles.
Ticket script — see "Per-ticket script".
tpl.env — Per-package env-var template. Declares the env vars the service needs. Used by bootstrap to populate .env on first install.
Tunnel — asd-managed reverse SSH connection to a sish-compatible tunnel server. Brings PMA's services public. See /asd/internals/tunnels.
Verify phase — Phase 4 of release-run. Drift check + health probes. Must show 0 actions for the release to be considered successful.
Workspace — .asd/workspace/. Per-project runtime state (registry, backups, caddy state file, release state files). Gitignored. Per-machine.