# Quickstart

This kit pins Plugin API `1.0.0` and kit `1.0.0`.
Plugin API major 1 and the combinations in
[compatibility.md](compatibility.md) are the v1 support boundary. Every public
runtime is personal-vault only.

## Prerequisites

- Node.js 20 or newer, including npm.
- A personal Thortiq vault. Shared workspaces do not run Plugin API 1 plugins.
- Internet access to install third-party template dependencies. The kit
  includes every Thortiq package, but not React, TypeScript, esbuild, or Vitest.

Create projects outside every Thortiq vault. Never use private notes, live
provider responses, or credentials as development fixtures.

## Download and extract

Download the complete immutable kit:

[Download Thortiq Plugin Developer Kit 1.0.0](/markdown/developer/plugin-kit/1.0.0/thortiq-plugin-kit-1.0.0.tar)

The adjacent
[release manifest](/markdown/developer/plugin-kit/1.0.0/release-manifest.json)
contains the archive byte count and SHA-256 digest. Extract the archive with
your operating system's archive utility or:

```sh
tar -xf thortiq-plugin-kit-1.0.0.tar
cd thortiq-plugin-kit
```

## Create a project

Choose `native`, `sandboxed-page`, or `live-sandboxed` using
[runtime-choice.md](runtime-choice.md), then run the bundled bootstrap:

```sh
node bootstrap.mjs \
  --name my-plugin \
  --template vanilla \
  ./my-plugin
```

Templates are `vanilla`, `react`, `sandbox`, and `live`. Run
`node bootstrap.mjs --help` for optional IDs, names, features, and the
`--skip-install` switch.

The bootstrap uses the bundled `create-thortiq-plugin` tarball, copies the
required exact Thortiq package tarballs into `vendor/thortiq/`, adds the
bundled CLI to the project, and runs `npm install` for third-party
dependencies. It does not require Thortiq packages to be published to npm.

## Let a coding agent guide the process

Download the
[Thortiq plugin-development skill](/markdown/developer/plugin-kit/1.0.0/kit/skills/thortiq-plugin-development/SKILL.md)
and install it using the skill or custom-instruction mechanism provided by
your coding agent. The skill interviews users in plain language, chooses the
safest suitable runtime, asks before downloading or installing anything, and
owns scaffolding, implementation, synthetic tests, packaging, and vault
installation.

Full automation requires an agent with permission-aware network, filesystem,
and terminal tools. A chat-only model can help specify or review a plugin but
cannot perform the download, build, tests, or installation.

## Build and install

```sh
cd my-plugin
npm run validate
npm test
npm run typecheck
npm run build
npx thortiq-plugin validate ./dist
npx thortiq-plugin package ./dist --out ../my-plugin.thortiq-plugin
npx thortiq-plugin install ../my-plugin.thortiq-plugin --vault "/path/to/vault"
```

Some templates omit checks they do not need. Installation is supported for
packaged `native` and `sandboxed-page` plugins. The external
`live-sandboxed` template can be authored and tested, but it is not packaged
or installed through the packaged-plugin archive command.

After installation, open Settings → Plugins in Thortiq, review the exact
package and permissions, then approve and enable it. Installation alone never
authorizes execution.

Thortiq does not execute package-manager scripts, install dependencies, or
compile a source tree in the vault.

Continue with [development-lifecycle.md](development-lifecycle.md) for exact
CLI commands, replacement, validated filesystem installation, migration, and
runtime approval. Coding-agent users should also read
[agent-workflow.md](agent-workflow.md).
