<SpecSection title="What this feature specifies" id="what-this-feature-specifies">
The **`beskid new`** command family — list, install, uninstall, and instantiate templates from registry, path, or git with interactive and flag-driven parameters.
</SpecSection>

<SpecSection title="Implementation anchors" id="implementation-anchors">
- `compiler/crates/beskid_cli/src/cli.rs` — subcommand tree
- `compiler/crates/beskid_cli/src/commands/new.rs` — Clap args and dispatch
- `compiler/crates/beskid_template::service` — list / install / uninstall / instantiate
- `compiler/crates/beskid_tools::registry` — shared pckg client helpers
- `compiler/crates/beskid_pckg` — registry download
</SpecSection>

<SpecSection title="Contract statement" id="contract-statement">
The Beskid CLI **must** expose a top-level **`beskid new`** command family for template discovery, installation, and instantiation. This is the **only** normative user entrypoint for scaffolding; `beskid pckg` remains publish/upload only.
</SpecSection>

<SpecSection title="Command taxonomy" id="command-taxonomy">
| Command | Obligation |
| --- | --- |
| `beskid new list` | List installed and optionally online templates |
| `beskid new install <package\|path\|git>` | Cache template for offline use |
| `beskid new uninstall <shortName\|package>` | Remove cached template |
| `beskid new <shortName> [options]` | Instantiate installed template by short name |
| `beskid new --path ...` | Instantiate without prior install |
| `beskid new --git ...` | Instantiate from git source |
| `beskid new --package <id>[@version]` | Instantiate from registry (install if needed) |

Global options documented in [contracts and edge cases](./contracts-and-edge-cases/).
</SpecSection>

<SpecSection title="First-party templates" id="first-party-templates">
When the registry is reachable, the CLI **must** resolve **`beskid.templates.console`**, **`beskid.templates.lib`**, and **`beskid.templates.project`** from pckg—not from files shipped inside the CLI binary. Short names **`console`**, **`lib`**, and **`template`** map to those packages when unambiguous.
</SpecSection>

<SpecSection title="Decisions" id="decisions">
No open decisions. Closed choices: **`D-TOOL-SCAFF-0001`** (`beskid new` command), **`0002`** (interactive modes), **`0003`** (update check on instantiate)—see **`adr/`** and the **ADRs** tab.
</SpecSection>

## Decisions
<!-- spec:generate:adr-index -->
No open decisions. Closed choices are normative ADRs under **`adr/`** (`D-TOOL-SCAFF-0001` … `D-TOOL-SCAFF-0003`); use the reader **ADRs** tab for expandable detail.
<!-- /spec:generate:adr-index -->
## Articles
<!-- spec:generate:article-index -->
- [Contracts and edge cases](./articles/contracts-and-edge-cases/)
- [Design model](./articles/design-model/)
<!-- /spec:generate:article-index -->

## Context

Scaffolding entrypoint.

## Decision

Command **must** be `beskid new`.

## Consequences

See project-templates ADRs.

## Verification anchors

CLI command table.

## Context

Scaffolding entrypoint.

## Decision

Support interactive and non-interactive instantiation.

## Consequences

See project-templates ADRs.

## Verification anchors

CLI tests.

## Context

Scaffolding entrypoint.

## Decision

Run template update check when online.

## Consequences

See project-templates ADRs.

## Verification anchors

Mock registry test.

## Purpose and scope

Normative CLI flags and behaviors.

## Global flags (instantiate)

| Flag | Meaning |
| --- | --- |
| `-o`, `--output <path>` | Output directory or file (item templates) |
| `-n`, `--name <string>` | Primary name symbol (maps to default `name` symbol) |
| `--symbol <id>=<value>` | Repeatable symbol binding |
| `--no-interactive` | Fail if required symbols missing |
| `--force` | Allow non-empty output directory |
| `--path <dir>` | Template from local path |
| `--git <url>` | Template from git |
| `--git-ref <ref>` | Branch, tag, or commit |
| `--git-subpath <dir>` | Subdirectory within repo |
| `--package <id>[@version]` | Registry package (`packageKind: template`) |
| `--project <Project.proj>` | Host project for item templates |
| `--allow-yanked` | Continue after yanked warning |
| `--strict-post-actions` | Fail on unknown post-action id |
| `--allow-project-manifest` | Item template may write `Project.proj` |

## `beskid new list` flags

| Flag | Meaning |
| --- | --- |
| `--online` | Include registry search results |
| `--kind <project\|workspace\|item>` | Filter by `tags.type` |

## Interactive

When stdin is a TTY:

- Prompt for each required symbol without a CLI value.
- Confirm overwrite when output exists (unless `--force`).
- Confirm proceed when template is yanked (unless `--allow-yanked`).

## Examples

```bash
beskid new list --online
beskid new install beskid.templates.console
beskid new console -n MyApp -o ./MyApp
beskid new lib --symbol name=MyLib --no-interactive -o ./MyLib
beskid new --git https://git.example.com/templates --git-ref main --git-subpath lib -o ./Lib
beskid new contract --symbol contractName=Foo -o ./Src/Foo.bd --project ./App/Project.proj
```

## Edge cases

- **`beskid new console`** without install: auto-install latest from registry when online.
- **Ambiguous shortName**: error listing matching package ids.
- **CI**: document `beskid new ... --no-interactive` in guides.

## Purpose and scope

Tooling-side state and paths for the `beskid new` command family.

## Cache directory

| Path (under user config root) | Content |
| --- | --- |
| `templates/installed/<identity>/` | Extracted template tree + `manifest.snapshot.json` |
| `templates/git/<hash>/` | Git clone caches |
| `templates/registry-index.json` | Optional index of last-known registry versions for update checks |

Exact config root **must** match other Beskid CLI state (same resolver as `beskid pckg` auth config).

## Install record

`manifest.snapshot.json` stores:

- `identity`, `shortName`, `packageId`, `resolvedVersion`, `checksum`, `installedAt`
- `source`: `registry` \| `path` \| `git`
- `yanked`: boolean snapshot at install time

## Update check

On `beskid new <shortName>` (and `--package`):

1. Read installed `resolvedVersion`.
2. Query registry for latest non-yanked version.
3. If newer: print update message (non-fatal).
4. If current is yanked: print warning (see contracts).

## Online vs offline

| Mode | Behavior |
| --- | --- |
| Registry reachable | Prefer download of `beskid.templates.*`; update check enabled |
| Offline | Use cache only; `list` shows installed; warn if update check skipped |

## Exit codes

| Code | Meaning |
| --- | --- |
| 0 | Success |
| 1 | User error (validation, collision) |
| 2 | Engine or I/O failure |
| 3 | Registry auth or network failure when required |

## Code anchors

- `compiler/crates/beskid_cli/src/cli.rs` — subcommand registration
- `compiler/crates/beskid_pckg` — download API