---
name: thortiq-plugin-development
description: Guide a non-technical user from a plain-language Thortiq customization idea through requirements, safe runtime selection, developer-kit acquisition, scaffolding, implementation, synthetic testing, packaging, and installation. Use when asked to create, build, test, install, change, or plan a Thortiq plugin or live customization, including when the user has no Thortiq source repository or development setup.
---

# Thortiq plugin development

Own the technical workflow. Ask the user about outcomes and consent, not
frameworks, manifests, runtimes, permissions, package commands, or file paths
unless a path cannot be discovered safely.

## Check capabilities

Require an agent environment with:

- permission-aware network downloads;
- filesystem and terminal tools;
- Node.js 20 or newer and npm; and
- access to the intended machine if installation into its vault is requested.

If any capability is absent, explain exactly which steps cannot be automated.
A chat-only model can prepare requirements or source text, but cannot truthfully
claim to download, test, package, or install a plugin.

## Establish the workspace

Inspect the current task-local workspace before asking questions. Never search
through, use, or modify a live vault as a development workspace or fixture.

Look for an extracted, compatible `thortiq-plugin-kit` and a matching
`release-manifest.json`. Version 1 uses:

- kit:
  `https://thortiq.com/markdown/developer/plugin-kit/1.0.0/thortiq-plugin-kit-1.0.0.tar`
- release manifest:
  `https://thortiq.com/markdown/developer/plugin-kit/1.0.0/release-manifest.json`

If the kit is absent:

1. Propose a clearly named development directory outside every directory
   containing `.thortiq`.
2. Ask permission to download and extract the exact kit there.
3. After permission, download both files over HTTPS.
4. Verify the archive byte count and SHA-256 against the release manifest
   before extraction. Stop on any mismatch.
5. Extract without overwriting an unrelated existing directory.

Do not install global npm packages. The kit carries the exact Thortiq packages.
Internet access is still needed for pinned third-party development packages.

## Understand the customization

Start with one plain-language question:

> What would you like Thortiq to do? Describe what you would expect to see or
> be able to do when it is working.

Infer as much as possible. Ask short follow-ups only for requirements that
materially affect behavior or authority:

- where the feature should appear;
- what information it reads or changes;
- whether it contacts an external service;
- whether it runs only on demand or on a schedule;
- any user-adjustable settings; and
- one synthetic example suitable for a test.

Never request real vault content, passwords, tokens, API keys, or production
service responses. Use placeholders and synthetic fixtures.

Summarize the proposed behavior, data access, external origins, and trust level
in plain language. Ask for approval before implementation when the plan would
write files, contact a new origin, or require full-trust native code.

## Choose the implementation

Choose the runtime and template without asking the user to understand them:

1. Prefer `sandbox` for a self-contained page, dashboard, form, visualization,
   importer, or workflow whose Thortiq access fits the public capability API.
2. Choose `vanilla` native only when the feature must use trusted host
   components, editor integration, mounted SearchView/Markdown components, or
   another capability unavailable to a sandbox. State clearly that native code
   is full-trust before proceeding.
3. Choose `react` native only when native host integration is required and the
   interface complexity materially benefits from React; otherwise prefer
   `vanilla`.
4. Choose `live` only when the agent has an actual Thortiq-managed live
   customization authoring channel. The external packaged-plugin CLI cannot
   install a live project. Otherwise choose the safest installable packaged
   runtime.

Request only the minimum permissions, connections, settings, secrets, jobs,
and contributions needed. Route network access through declared HTTPS
connections; never add ambient `fetch`, filesystem access, or application
internal imports.

## Scaffold and implement

From the extracted kit, create a separate project:

```sh
node bootstrap.mjs \
  --name <project-name> \
  --template <vanilla|react|sandbox|live> \
  <safe-project-directory>
```

The bootstrap invokes the kit's exact bundled `create-thortiq-plugin` package
and rewrites the project to use its local Thortiq package archives.

Then read, in order:

1. the kit's `docs/quickstart.md`, `docs/runtime-choice.md`,
   `docs/compatibility.md`, `docs/development-lifecycle.md`, and relevant
   recipes;
2. generated `PLUGIN_TASK.md`;
3. generated `AGENTS.md`;
4. `node_modules/@thortiq/plugin-api/README.md` and `LIMITS.md`; and
5. the matching schemas under `@thortiq/plugin-api/schemas/`.

Treat those version-pinned files as authoritative. Implement only public API
behavior. Keep every test deterministic and synthetic. Update the manifest,
integrity data, tests, and user-facing diagnostics together.

## Verify and repair

Run every generated check that exists:

```sh
npm run validate
npm test
npm run typecheck
npm run build
npx thortiq-plugin validate ./dist
npx thortiq-plugin test ./dist
npx thortiq-plugin package ./dist --out ../<plugin-id>.thortiq-plugin
```

Live projects validate and test but do not use the packaged build/install
commands. For packaged plugins, inspect the closed `dist/` payload and archive.
Fix failures and repeat all affected checks. Never bypass a validator, loosen a
security boundary merely to pass, or claim success from partial output.

## Install safely

Installation is a separate, explicit mutation of a personal vault:

1. Discover candidate vaults only from paths the user or application has
   already placed in scope. If the target is ambiguous, ask which named vault
   to use.
2. Present a concise review: plugin name/version, runtime and trust level,
   permissions, HTTPS origins, settings/secrets, and checks run.
3. Ask permission to install that exact archive into that exact vault.
4. Run:

   ```sh
   npx thortiq-plugin install ../<plugin-id>.thortiq-plugin \
     --vault "<vault-path>"
   ```

5. Never use `--replace` without separate approval after explaining which
   installed version will be replaced.

Installation does not authorize execution. Do not approve trust, network
origins, or enable the plugin on the user's behalf. Open or direct the user to
Settings → Plugins, explain the final review in plain language, and ask them to
approve and enable it there. Report the exact project, archive, install
location, and verification results.
