.project configuration

.project is a file in the selected local project root. Current Runtime can preview/apply project initialization (praxis_project_init_preview / _apply) where available. The source canon and code checkout may each have their own configuration. There are no canonRepo or codeRepo fields in this example; pass the separate paths explicitly to source tools. Runtime resolves one selected root and does not import a sibling checkout.

Counter example:

stack:
  - node
  - javascript
requirementsFormat: user-story-gherkin
requiredArtifacts: []
environments: []
knowledge:
  ref: main
jira: {}
quality:
  test: npm test

Field	Required	Meaning
stack	inferred	Languages/tools for Skills
requirementsFormat	inferred	How BA writes AC
requiredArtifacts	no	Extra files to demand
environments	no	Named envs
knowledge.ref	no	Knowledge corpus ref
jira	no	Non-secret Jira hints. Never a token
quality.test	for Developer complete / Quality	Command actually run (e.g. npm test)
quality.build / coverage / start	no	Optional Quality commands

Secrets do not belong here. See Secrets.

Runtime settings (extension and environment)

Where settings come from

Client	How settings reach the Runtime
Claude Desktop with the MCPB	Extension settings (user_config) are mapped to environment variables for the server process. Sensitive fields are stored in the operating system secret vault
Claude Code, Desktop Code, Cowork (plugin)	The plugin server inherits the environment of the client process. Set variables before starting the client, or in your user Claude Code settings. Claude Code also applies the env block of a repository's .claude/settings.json, but any env entry there makes Praxis refuse protected actions (Approvals)
CLI and CI	PRAXIS_* environment variables
A repository file	.env.praxis, .env, .env.praxis.local in the repository root, with restrictions below

All settings are optional. Local workflows need none of them.

Extension settings

Authoritative list: JIRA_USER_CONFIG and JIRA_ENV_MAP in praxis-runtime/tools/scripts/claude-extensions-shared.mjs.

Setting key	Environment variable	Sensitive	Purpose
jira_base_url	PRAXIS_JIRA_BASE_URL	no	Jira Cloud or Data Center origin, no trailing slash
jira_email	PRAXIS_JIRA_EMAIL	no	Account email (Cloud: email plus API token)
jira_project_key	PRAXIS_JIRA_PROJECT_KEY	no	Jira project key, for example PRX
jira_token	PRAXIS_JIRA_TOKEN	yes	Jira API token
github_token	PRAXIS_GITHUB_TOKEN	yes	GitHub personal access token with repo scope (PAT, not OAuth) for Pull Requests and Actions status
github_api_url	PRAXIS_GITHUB_API_URL	no	Optional: https://api.github.com or https://HOST/api/v3 for GitHub Enterprise; not a git remote URL
gitlab_token	PRAXIS_GITLAB_TOKEN	yes	GitLab personal access token (api scope) for Merge Requests
gitlab_base_url	PRAXIS_GITLAB_BASE_URL	no	Optional GitLab origin, no trailing slash

There is no approval setting. The Approval mode setting (approval_mode) was removed in 0.1.0-alpha.49.2, and a value entered earlier is ignored.

A blank optional setting reaches the process as the unexpanded text ${user_config.NAME}. The Runtime treats any PRAXIS_* value of the form ${...} as unset and lists the names in praxis_doctor as hostPlaceholdersIgnored.

Jira is considered configured when base URL, email, project key and token are all set. Jira operations are available when base URL, token and project key are set (capabilities.jiraConfig in the doctor). Otherwise Jira tools return JIRA_CONFIG_UNAVAILABLE naming the missing settings; local tools are unaffected.

Other environment variables read by the Runtime

Variable	Purpose
PRAXIS_STATE_HOME	Relocates ~/.praxis (decision journal and diagnostics log). Protected actions are refused while it points inside the repository
PRAXIS_APPROVAL_MIN_ANSWER_MS	Minimum time before a dialog answer can be taken (default 1000 ms). Only a longer value is taken; a lower one is ignored
PRAXIS_APPROVAL_MODE, PRAXIS_APPROVAL_PAGE, PRAXIS_APPROVAL_BROWSER, PRAXIS_APPROVAL_PAGE_MIN_MS	PRAXIS_APPROVAL_MODE is retired (Trusted Client and host-permission were removed in 0.1.0-alpha.49.2); the others are test switches. A shipped Runtime ignores them all and the doctor lists them in approval.ignoredEnvironment
PRAXIS_QUALITY_PORT, PRAXIS_QUALITY_URL, PRAXIS_QUALITY_DB, PRAXIS_QUALITY_ALLOWED_ROOT, PRAXIS_QUALITY_HOST	Local Quality service port, URL, database and root. When the Runtime starts the service it sets port, database, allowed root (the repository) and host 127.0.0.1 itself
PRAXIS_QUALITY_STARTUP_TIMEOUT_MS	Quality service start timeout
PRAXIS_SKIP_DOTENV=1	Do not read repository .env files
PRAXIS_BUILD_INFO, PRAXIS_BUNDLE_KIND	Build identity embedded in a shipped bundle; not for users to set
PRAXIS_TEST_APPROVALS, PRAXIS_TEST_*	Test harness only; inert in a shipped Runtime

This is the set seen in the sources; settings used only by acceptance scripts are not listed.

What a repository .env may and may not set

Core's loadPraxisDotenv (praxis-core, packages/cli/src/operations.ts; tests in dotenv-allowlist.test.ts and dotenv-trust.test.ts) reads .env.praxis, .env and .env.praxis.local, only at the repository root, through an allowlist. Rules:

Rule	Behaviour
Allowlist	Only PRAXIS_JIRA_PROJECT_KEY, the Jira issue-type, field and transition names (PRAXIS_JIRA_*_TYPE, *_TYPE_ID, PRAXIS_JIRA_WORK_PACKAGE_TYPE, PRAXIS_JIRA_STORY_POINTS_FIELD, PRAXIS_JIRA_ARCHITECT_ESTIMATE_FIELD, PRAXIS_JIRA_TRANSITION_*), PRAXIS_GIT_PROVIDER and PRAXIS_WORK_PACKAGE_MAX_HOURS are loaded, each only with a value of the right shape
Never loaded	Approval variables (PRAXIS_APPROVAL_*), test switches (PRAXIS_TEST_*, PRAXIS_FIXTURE_*), PRAXIS_STATE_HOME, PRAXIS_SKIP_DOTENV, every URL, e-mail and credential (PRAXIS_JIRA_BASE_URL, *_TOKEN, PRAXIS_GITHUB_*, PRAXIS_GITLAB_*), Quality service settings, and any non-Praxis variable such as PATH, BROWSER or NODE_OPTIONS
Real environment wins	A key already set in the process environment is never overwritten by a file; among the three files the first one read wins
Scope	Values from one repository's file apply only to calls for that repository; only regular files up to 64 KB are read
Visibility	praxis_doctor reports names only, never values: dotenvRefused ([{ key, reason }], reason not-allowed, trust or bad-value-shape), dotenvLoaded, and nextSteps
Opt out	PRAXIS_SKIP_DOTENV=1, from the real environment only

Reason: files in a repository are writable by the agent, so they must not decide how a change is approved. Since 0.1.0-alpha.49.2 no file, setting or environment variable decides it: only the client's own dialog does (Approvals).

PRAXIS_STATE_HOME inside the repository would put the journal where the agent can edit it, so protected actions are refused while the state home is inside the repository.

Secrets handling

• Tokens are entered in the extension settings (stored in the OS secret vault) or in the environment of the operator. Never paste a token into chat.
• praxis_doctor and the provider diagnostics report only whether each setting is configured, never its value.
• The diagnostics log records tool names, durations, result codes and declared capability keys, not arguments, plan text, tokens or file contents.
• Workflow state written to .praxis/ passes through the Runtime's redaction. praxis-state-policy.mjs scan checks committable files for credentials and home paths and reports the kind and location, never the value.
• A repository .env never supplies PRAXIS_JIRA_TOKEN, PRAXIS_GITHUB_TOKEN, PRAXIS_GITLAB_TOKEN or any URL: a file the agent can write could otherwise send a request that carries your real token to another host. Put them in the extension settings or your shell.
• Git Delivery never prints credentials; praxis_developer_git_status reports provider and identity state only.