# SharkCraft 0.1.0-alpha.2 — public alpha

This is the first **public alpha** of SharkCraft. It is intentionally
narrow in scope and explicit about the parts that are not finished yet.

## What SharkCraft is

A deterministic, **local-first** toolkit that gives AI coding agents
durable project context:

- A CLI (`shrk`) that is the only write path.
- A read-only MCP server that mirrors the CLI's queryable surface.
- A library of typed assets — knowledge / rules / paths / templates /
  pipelines / presets / boundaries / packs.
- A local, read-only **dashboard** (`shrk dashboard`) backed by the same
  data.
- Bundles, dev sessions, briefs, reviews, impact, report-site, demo
  scripts, demo workflow CI YAMLs, agent handoffs, repository maps,
  pack release/compat tooling, release-smoke harness and a release-
  readiness aggregator.

## What SharkCraft is NOT

- It is **not** an autonomous write-agent. SharkCraft never executes
  arbitrary code, never publishes, never posts on the network, never
  modifies a user's repo without an explicit `shrk apply` step.
- It is **not** an AI runtime. No model is called inside the engine.
- It is **not** a SaaS. There is no cloud component, no billing surface,
  no telemetry, no licensing key.

## Safety pledge

- **MCP never writes.** All read-only by construction; the dashboard is
  GET/HEAD only.
- **`shrk gen` is dry-run by default.** Apply requires `--verify-signature`
  on signed plans.
- **Pack-contributed verification commands are NOT auto-run.** Only
  commands in `sharkcraft.config.ts verificationCommands[]` are
  eligible for `shrk apply --validate`.
- **Demo scripts refuse to emit destructive lines.** `rm -rf` /
  `dd if=` / `mkfs` are statically blocked.
- **Release smoke writes only into temp fixtures.** `assertSafeWrites`
  raises a `forbidden-artifacts` finding if a step leaks outside the
  allowed prefixes.

## Highlights since R0

- **Onboarding** with three-way diff, adopt patches, and signed checkpoints
  (with age expiry — R16).
- **Generation flow**: dry-run → plan → review → apply, all signed.
- **Brief / dev sessions / bundles** for tracked, replayable work.
- **Review packets** (v2 + v3) and **report site** with optional Mermaid
  / Graphviz SVG render (R15).
- **CI scaffolds** for GitHub Actions, GitLab, Bitbucket, Jenkins,
  Azure DevOps + permissions audit + R16 fix-preview.
- **Release readiness** aggregator (R15) + R17 strict additions for
  release notes, public-alpha limitations, external quickstart,
  CHANGELOG.
- **Release smoke** (R16) + R17 content assertions + matrix mode +
  tarball install smoke.
- **Agent handoff** packet (R16) and **repository map** (R16).
- **Diagnostics registry** with CLI + MCP lookup (R17).

## Runtime requirements

- **Bun ≥ 1.1** for development.
- A **Node-compatible** publish path is exercised by
  `bun run release:smoke-test` and `bun run compat:node`. Bun-specific
  runtime APIs are deliberately not used in `dist/`.

## Quick install / run

Pre-publish, run from the monorepo:

```bash
bun install
bun run shrk doctor
bun run shrk start-here
```

Post-publish, the package will be consumable from npm. See
[`docs/external-repo-quickstart.md`](../external-repo-quickstart.md).

## Compatibility notes

- The CLI tries to remain backwards-compatible across patch versions.
- MCP tool names are stable in `0.1.x`. The audit list
  (`get_command_catalog` audit feed) is kept in sync with the runtime
  list and exercised by an integration test.
- Pack manifest schema (`sharkcraft.pack/v1`) is the contract — pack
  authors who follow it should not need changes for `0.1.x`.

## Known limitations (read before adoption)

See [`docs/public-alpha-limitations.md`](../public-alpha-limitations.md)
for the canonical list. Highlights:

- The release smoke harness assumes the SharkCraft monorepo layout
  (it shells out to `bun packages/cli/src/main.ts`). The `--tarball`
  mode (R17) covers the published shape via `release:smoke-test`.
- `shrk packs compat --dist-aware` only walks `dist/*.{js,mjs,cjs}`;
  nested entry points need the consumer-root to be the parent.
- The dashboard ships React + Vite assets — it is JS-loaded, but the
  server is GET/HEAD only.
- Bundle rename detection uses fixed-weight similarity; some renames
  with large content drift still surface as remove+add.

## Do not use as an autonomous write agent

SharkCraft makes a repo *operable by* AI agents — it does not *act as*
one. The CLI gates the write step deliberately. Treat every plan
produced by an agent as a human-review artifact.

— SharkCraft team