--- 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 \ --template \ ``` 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 ../.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 ../.thortiq-plugin \ --vault "" ``` 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.