# Grok Compatibility Model

This reference separates the Grok-portable baseline from behavior supplied by the `Grok agent environment` harness layer. It is not a routing table, support policy, or second control plane. For local route choice, helper fit, and Impeccable layering, keep using `reference/routing-guidance.md`.

## Native Grok portable baseline

Native portability means the surface follows current Grok docs and schema without needing the `Grok agent environment` plugin.

1. Use `Grok.json` or `Grok.jsonc` for project Grok config. The same schema is used for global config under `~/.config/Grok/Grok.json`.
2. Use standard `reference/` directories for local assets, including `skills/<name>/SKILL.md` and `reference/commands/*.md`.
3. Use native `skills.paths` in `Grok.json` when extra skill folders are needed. Current Grok schema also documents `skills.urls`. It does not define `skills.sources` as a native config key.
4. Keep native skill frontmatter to documented fields: `name`, `description`, `license`, `compatibility`, and `metadata`. Grok docs describe `metadata` as an optional string-to-string map.
5. Keep native command definitions on documented command fields such as `description`, `agent`, `model`, `subtask`, and the command prompt template.
6. Use the singular `permission` config term for Grok tool, task, skill, and agent access rules. This document uses `permission` only in that native Grok sense.

Native Grok does not promise this bundle's local routing policy, workspace placement convention, Impeccable wrapper taxonomy, or `Grok agent environment` task and category behavior. Those are documentation-backed bundle rules or harness behavior, not portable Grok guarantees.

## Grok agent environment enhanced behavior

Enhanced behavior means the `Grok agent environment` plugin or this local companion bundle adds meaning beyond native Grok.

1. `Grok agent environment` is registered from Grok config, normally in `Grok.json`, through the plugin entry `Grok agent environment`. The legacy plugin entry `oh-my-Grok` still loads during the rename transition.
2. The plugin reads user and walked project configs named `reference/Grok agent environment.jsonc`, `reference/Grok agent environment.json`, `reference/oh-my-Grok.jsonc`, or `reference/oh-my-Grok.json` during the transition.
3. This toolkit's `reference/Grok agent environment.jsonc` is a narrow schema-compatible plugin config placeholder, not path wiring. From the toolkit repo root, `Grok agent environment` v4.3.0 project discovery loads `reference/skills` and `reference/commands` automatically; reference files remain documentation linked by those assets.
4. `skills.sources` is an `Grok agent environment` skill-loading config shape for extra skill sources outside default project discovery, not the same thing as native Grok `skills.paths`. The enhanced source entries may include a local `path`, `recursive`, or `glob` setting, or a remote source string. It does not configure command or reference roots.
5. Enhanced skill definitions may carry `allowed-tools`, `argument-hint`, `model`, `agent`, `subtask`, `license`, `compatibility`, and `metadata` in the plugin schema. In this bundle, `allowed-tools` and `argument-hint` should be read as enhanced metadata unless current native Grok docs add them later.
6. The Impeccable layer uses enhanced local metadata on the consolidated `impeccable` skill, including `allowed-tools: Bash(npx impeccable *)` and an `argument-hint`. Local compatibility wrappers stay thin, grant-free aliases for the consolidated `/impeccable` command model.
7. Category routing, background agents, built-in MCP injection, Team Mode, task persistence, and hashline editing are harness features. They can improve local operation, but they are not native Grok guarantees.
8. The `grok-toolkit` CLI package is distribution mechanics only. It installs or updates this bundle's project-local files from package contents and `toolkit-manifest.json`; it is not native Grok configuration, not a plugin registration method, and not `Grok agent environment` path wiring.

## Boundary rules for this toolkit

1. Do not add custom top-level keys to native `Grok.json` examples. Put `Grok agent environment` settings in the plugin config files instead.
2. Do not add top-level `paths` to `reference/Grok agent environment.jsonc`; v4.3.0 exposes top-level `skills`, while local `reference/skills` and `reference/commands` are project-discovered from the toolkit root.
3. Do not describe `reference/Grok agent environment.jsonc` or `reference/oh-my-Grok.jsonc` as native Grok config files. They are enhanced plugin config files.
4. For `allowed-tools`, `argument-hint`, or `user-invocable`, do not claim native support unless current Grok docs or schema prove it. At the time of this reference, current native docs list a smaller skill frontmatter set and ignore unknown skill frontmatter fields.
5. Do not use `skills.sources` when documenting native Grok. Use `skills.paths` for native extra skill folders and reserve `skills.sources` for the enhanced layer.
6. Do not use the package CLI as evidence that `reference/Grok agent environment.jsonc` controls command, reference, routing, or workspace paths.
7. If a local document needs routing or helper behavior, link to `reference/routing-guidance.md`. If it needs native-versus-enhanced config or metadata wording, link here.

## Quick reference

| Question | Portable answer | Enhanced answer |
| --- | --- | --- |
| Where does project Grok config live? | `Grok.json` or `Grok.jsonc` | Plugin config may also live in `reference/Grok agent environment.jsonc` or transitional `reference/oh-my-Grok.jsonc`; local toolkit assets are discovered from the active toolkit root |
| How are extra skill folders named? | `skills.paths` in native config | `skills.sources` in `Grok agent environment` config for extra skill sources; default `reference/skills` needs no explicit config |
| Which skill metadata is native? | `name`, `description`, `license`, `compatibility`, `metadata` | `allowed-tools`, `argument-hint`, and richer plugin skill definitions are enhanced |
| How are access rules named? | `permission` | Agent and category settings may add enhanced behavior, but `permission` stays the native Grok term |
| Does routing happen here? | No. Native Grok discovers assets and runs commands or skills | No. This reference explains compatibility only. Routing remains in `reference/routing-guidance.md` |
| Is the npm CLI native Grok config? | No. It is outside the native config schema | No. It is package distribution mechanics only, not `Grok agent environment` path wiring |