# Add Tinka to this project

Tinka is a small local canvas for experiments, alternatives, and notes. This is
the official agent setup entry point for https://tinka.metal-sole.com/.
Source and releases: https://github.com/bladnman/tinka. No agent skill is required.

## First, check this project

Read its AGENTS.md and TINKA.md. Follow an existing Tinka installation's own
instructions and version pin. If its app is missing, run its checked-in
`tinka/setup.mjs` to restore it. Preserve all boards, earlier rounds, stable IDs,
assets, and notes. Do not upgrade, move boards, or create samples unless asked.

## New installation

Requires Node.js 22+ and macOS or Linux. No runtime npm dependencies.

1. Resolve the target project's absolute path and label. Use visible `tinka/`
   for tooling and `design/boards/` for durable content, unless the project
   specifies another layout. Read the source README's manual setup section.
2. Read https://api.github.com/repos/bladnman/tinka/releases/latest. Select a
   non-draft, non-prerelease release. Download `tinka-install.mjs` and
   `tinka-install.mjs.sha256` from that same release tag into a temporary folder.
   Verify the installer's SHA-256 against the sidecar before running it. Use
   the tag's version in place of VERSION below, without its leading `v`.
3. Run the verified helper for this project:

   ```sh
   node /absolute/temporary/tinka-install.mjs --project /absolute/project --label "Project name" --version VERSION
   node /absolute/project/tinka/app/cli.mjs start --config /absolute/project/tinka/local/config.json
   ```

   The helper verifies the matching app archive and prepares portable project
   instructions, a restore helper, version pin, and an empty boards folder.
4. Read the installed app's `docs/AGENT.md` and `docs/PROTOCOL.md` before working
   on boards. These are the authority for the installed version. New boards
   also carry their own AGENTS.md. Experiments use ordinary files; no Tinka SDK.
5. Verify `/api/health` at the actual URL printed by start. Confirm the project
   label and canonical config path match this project, then report that URL.
   Keep each project independent. Never stop another service to free a port.

## Make the work travel

Commit TINKA.md, the project's AGENTS.md pointer, `tinka/setup.mjs`,
`tinka/project.json`, `tinka/.gitignore`, and complete boards including assets,
history, handoffs, and `.state/notes.json`. Check that ignore rules allow notes.
The replaceable `tinka/app/` and machine-local `tinka/local/` stay ignored.

For offline fresh checkouts, also commit the selected release's
`tinka/packages/tinka-vVERSION.zip` and matching `.zip.sha256` sidecar. Download
both from the same tag; do not rename another version's package. With Node.js
22+ available, `node tinka/setup.mjs` restores the pinned bundle offline, then
start with the project's local config as above. Verify a clean checkout at a
different path restores its boards and notes before promising portability.

## More information

- Website and working public examples: https://tinka.metal-sole.com/
- Source and full manual setup: https://github.com/bladnman/tinka#manual-setup
- Release metadata: https://api.github.com/repos/bladnman/tinka/releases/latest
- Source agent guide: https://github.com/bladnman/tinka/blob/main/docs/AGENT.md

An install request authorizes setup for the selected project. Board creation,
experiments, upgrades, and publication follow the user's requested scope.