`setting`

A setting is the configuration part of a setup: parameters, modes, feature flags, preferences, thresholds, and other values the harness or the provider knows how to apply.

A setting answers the question: which non-secret parameters should be pinned?

It does not answer "what standing rule should the agent remember?" (), "what must run on an event?" (), or "which MCP servers are declared in this same file?" (that finding is kind , native_role mcp_client_config).

A setting must not hold secrets. If a value is a token, a password, a private key, or a credential, it goes through a supported secret store, not through a component's passport.

!!! warning "One file can be a setting and an MCP finding"

Codex, OpenCode, and Grok Build keep client MCP servers inside a file also declared as setting:

File existence proves the setting, never the servers. The file becomes an mcp finding only when at least one server is declared under that key. One file can produce two findings of different types. Adopt with --kind when the path is claimed by both.

Only server names are read into evidence_refs. Values (command, args, URL, headers, env) are never read.

Neighbours

Choose setting when the provider or the CLI reads a value. Choose instruction when the agent should be told in prose. Choose hook or command if the value starts an action.

Recommended package structure

setting is declarative. --language is none. A setting requires a concrete harness: portable is refused. Claude Code projects settings.json; Codex and Grok project config.toml; OpenCode projects opencode.json.

strict-mode/                       # component-scaffold/3
├── .ai-stp-template.json
├── .gitignore
├── README.md
├── component-passport.json
├── eval-profile.json
├── source/
│   └── settings.json
└── projections/claude-code/
    └── settings.json

ai-stp component scaffold plan \
  --type setting \
  --language none \
  --harness claude-code \
  --name strict-mode \
  --output ./strict-mode \
  --json

ai-stp component scaffold apply \
  --type setting \
  --language none \
  --harness claude-code \
  --name strict-mode \
  --output ./strict-mode \
  --expected-plan-digest <digest> \
  --json

--language for a setting is none. The kind is declarative.

Put in the artifact only values that may be stored:

For required_env, record names and purposes in the passport, never values.

There is no ai-stp component setting validate. Structural readiness is component passport validate. Kind-specific specification checking exists only for .

Standards and frameworks

There is no independent setting specification comparable to the Agent Skills Specification or to MCP. Each harness documents its own configuration file.

Cite layout_source from ai-stp component discover --json when classification is uncertain. Do not guess a neighbour's path, and do not treat a settings file as MCP merely because it exists.

NVIDIA SkillSpector and Cisco Skill Scanner are skill scanners. They do not validate settings.

Native layouts per harness

Discovery only reports layouts that are declared. Exact paths on a machine come from ai-stp component discover --json. Each finding carries layout_source. If classification is uncertain, show that field; do not guess a neighbour's path.

From the discovery matrix:

A declared path still belongs to an untrusted machine. Discovery does not read secret values out of a settings file to "check" them.

ai-stp component discover --root . --json
ai-stp toolchain harness-capabilities --json

If the same path answers to more than one kind, name --kind on adopt.

ai-stp component adopt --path <source_path> --kind setting --json

Versions are `X.Y`, not SemVer

A published setting version is immutable and has the form X.Y. There is no patch number. Changing a flag, a mode, or a threshold is a new version. Updating a setting inside a setup is a new setup version.

ai-stp component version list --id <stable_id> --json
ai-stp component version release --id <stable_id> --json

--major opens the next major line. A major line is a separate access boundary.

What `ai_stp` checks

The catalog percent and the required-versus-optional split are explained on Security checks. For a setting, expect at least:

• structure, digest, license, tags, source repository;
• bounded unpack and path denylist;
• secret scanning (secrets_heuristic, and Gitleaks when enabled);
• prompt-injection and hidden-content rules.

A passed scan reduces known risk. It is not a guarantee that the configuration is harmless. Required checks that fail or cannot run block publication.

Before install, also look at:

author_verified and component_verified are independent. Neither is a safety guarantee.

Related CLI commands

Only commands that exist. Flags always from the CLI pages, and always --json. The executable is ai-stp (package ai-stp-cli). There is no component inspect and no setup show. The only kind-specific validate is ai-stp component skill validate.

This kind, specifically: there is no component setting validate. Use passport validation.

ai-stp component passport validate --id <stable_id> --json

Author, adopt, publish:

ai-stp component discover --root . --json
ai-stp component adopt --path <source_path> --json
ai-stp component passport validate --id <stable_id> --json
ai-stp component version release --id <stable_id> --json
ai-stp publication plan --id <stable_id> --version 1.0 --json
ai-stp publication confirm --plan-id <id> --plan-hash <hash> --confirm --json

Find, select, install:

ai-stp registry search --kind component --query <name> --json
ai-stp select eligibility --harness <id> --json
ai-stp install plan --json

A setting can also be an embedded member of a compose manifest. See Setups.

How a setting moves through `ai_stp`

=== "Author" The author publishes the setting from a public GitHub source, or imports it locally. The version pins an exact commit and subpath. Secret values stay out of the tree.

=== "Catalog" The catalog shows the parameters, the supported harnesses, the constraints, the author's trusted status and the component's own independent status.

=== "Compiler" The compiler checks for conflicts with other components of the setup and that the file structure suits the provider's projection.

=== "Provider" The provider shows the configuration diff and writes the native surface only after a plan, a digest and a confirmation.

Red flags

• Tokens, passwords, private keys, OAuth refresh tokens, or .env bodies in the setting, the passport, or README examples.
• Using a setting as a convenient place for a workflow, a hook, or a command.
• Labelling config.toml / opencode.json as MCP because the file exists, when the MCP key is empty.
• Opening the MCP block of a settings file to copy command, args, URL, headers, or env into a passport.
• experimental trust line without consent allow.
• Harness not in the component's compatibility list.
• "Latest" or a branch name instead of an exact X.Y and commit.
• Treating author_verified as component_verified.
• Copying a settings file into a target instead of going through the provider plan.

??? question "Can a setting be used without publishing it" Yes. Your own, imported or exactly pinned setting can be used after local checks. It does not thereby become platform-verified, and it must be shown as exactly what it is: a local or pinned object (local_owner_or_pinned). Secrets still do not belong in it.

Author checklist

1. Scaffold with --type setting --language none and keep the native file under source/.
2. Store only non-secret parameters. Record env names in the passport if the harness will need a credential later.
3. If the file also declares MCP servers, treat that as a separate finding. Do not put server values in this artifact.
4. Declare what the values change in the passport.
5. Run ai-stp component discover --root . --json and read layout_source, and native_role if a second finding appears.
6. component adopt --path <exact source_path> — add --kind setting when the path is also MCP.
7. Pin an exact public GitHub commit and subpath. No secrets in the tree.
8. component passport validate → component version release to mint immutable X.Y.
9. Publish through the publication path. In a setup, pin that X.Y.

Related: Authoring, Components, , .