@pina-rs/skill 0.0.0 → 0.10.0

package/README.md

@@ -1,3 +1,27 @@
 # @pina-rs/skill
 
-This is a placeholder release published by monochange to bootstrap trusted publishing.
+<p align="center">
+	<img src="https://raw.githubusercontent.com/pina-rs/pina/main/.github/assets/logo.png" alt="The Pina logo: a low-poly origami pineapple" width="140">
+</p>
+
+Agent guidance for creating, auditing, and maintaining Pina Solana programs.
+
+The skill covers project setup, discriminator-first data layouts, account validation, PDA design, IDL and client generation, SBF profiling, and proportionate verification. Its instructions preserve `no_std` compatibility and treat the checked-in project configuration as authoritative.
+
+## Install
+
+```sh
+npm install --global @pina-rs/skill
+pina-skill --install
+```
+
+The default destination is `$CODEX_HOME/skills/pina` when `CODEX_HOME` is set, otherwise `~/.codex/skills/pina`. Installation refuses to replace an existing skill directory.
+
+Inspect the source path or print manual installation instructions with:
+
+```sh
+pina-skill --print-path
+pina-skill --print-install
+```
+
+At runtime, agents begin with [SKILL.md](./SKILL.md) and load a focused file under [references](./references) only when the task needs it.

package/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: pina
+description: Create, audit, and maintain no_std Solana programs built with Pina and pinocchio. Use for Pina project setup, program identity, account and instruction authoring, PDA validation, diagnostics, IDL or client generation, SBF profiling, tests, and project upgrades.
+---
+
+# Pina
+
+Build Pina programs that are small, explicit, and safe at the account boundary. Preserve the project's chosen structure and commands unless the user asks for a redesign.
+
+## Establish the local contract
+
+Before changing code:
+
+1. Read the nearest `AGENTS.md`, `Cargo.toml`, `.cargo/config.toml`, and project documentation.
+2. Inspect the installed interface with `pina --help` and `pina <command> --help`; do not rely on remembered flags.
+3. Identify the program crate, its `pina` version and features, its entrypoint feature, and its existing test harness.
+4. Treat generated IDLs and clients as derived files. Find the repository's generation command before editing them.
+
+When no project exists, read [references/project-setup.md](references/project-setup.md). For an existing program, select only the reference that matches the task.
+
+## Non-negotiable program invariants
+
+- Preserve `no_std` compatibility for on-chain code. Keep host-only tooling and test dependencies outside the program runtime path.
+- Do not introduce `unsafe` code or unstable features.
+- Validate account identity, signer status, writability, ownership, and data shape before casts, mutation, lamport transfers, resize operations, or CPI.
+- Use explicit discriminator values and type-specific PDA seed namespaces. Prefer canonical bump validation.
+- Keep instruction dispatch deterministic: parse once, match explicitly, then construct and validate the accounts type for that instruction.
+- Maintain discriminator-first, fixed-layout storage types expected by Pina and zeropod. Do not place ordinary Rust `bool`, `String`, or variable-length collections in zero-copy account layouts.
+- Preserve error values and wire formats unless the user explicitly accepts a compatibility change.
+
+Read [references/program-authoring.md](references/program-authoring.md) before changing macros, account layouts, validation chains, PDAs, CPIs, or close/reallocation logic.
+
+## Workflow
+
+1. Inspect the smallest relevant surface and state the compatibility boundary: wire format, account layout, program ID, generated IDL, or CLI output.
+2. Make the narrowest idiomatic change. Reuse Pina validation and loader APIs instead of duplicating parsing or ownership checks.
+3. Add or update a regression test at the layer where the behavior is observable.
+4. Run focused tests first, then the repository's documented format, lint, build, and test commands. For a standalone project without task aliases, use Cargo commands from [references/testing.md](references/testing.md).
+5. Regenerate the IDL and clients when the public program surface changes. Review the diff before accepting generated output.
+
+## Task routing
+
+- Project creation, dependency features, entrypoint wiring, or workspace layout: read [references/project-setup.md](references/project-setup.md).
+- Accounts, instructions, discriminators, PDAs, validation, CPI, resize, or close behavior: read [references/program-authoring.md](references/program-authoring.md).
+- CLI discovery, project diagnostics, program keys, IDL extraction, Codama client generation, terminal docs, completions, or profiling: read [references/cli-and-codegen.md](references/cli-and-codegen.md).
+- Unit, Mollusk, SBF, generated-artifact, or release checks: read [references/testing.md](references/testing.md).
+
+Do not load every reference for routine edits.

package/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Pina"
+  short_description: "Build and maintain secure Pina programs"
+  default_prompt: "Use $pina to create or improve this Pina Solana program."
+
+policy:
+  allow_implicit_invocation: true

package/bin/pina-skill.cjs

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+"use strict";
+
+const { cpSync, existsSync, mkdirSync } = require("node:fs");
+const { homedir } = require("node:os");
+const path = require("node:path");
+
+const packageRoot = path.resolve(__dirname, "..");
+const skillEntries = Object.freeze(["SKILL.md", "agents", "references"]);
+
+function defaultDestination(environment = process.env) {
+	const codexHome = environment.CODEX_HOME || path.join(homedir(), ".codex");
+	return path.join(codexHome, "skills", "pina");
+}
+
+function installSkill(destination) {
+	const resolvedDestination = path.resolve(destination);
+	if (existsSync(resolvedDestination)) {
+		throw new Error(
+			`Refusing to replace existing skill directory: ${resolvedDestination}. ` +
+				"Remove or move it after reviewing your local changes, then run the installer again.",
+		);
+	}
+
+	mkdirSync(resolvedDestination, { recursive: true });
+	for (const entry of skillEntries) {
+		cpSync(
+			path.join(packageRoot, entry),
+			path.join(resolvedDestination, entry),
+			{
+				recursive: true,
+			},
+		);
+	}
+
+	return resolvedDestination;
+}
+
+function helpText() {
+	return `Install or locate the Pina agent skill.
+
+Usage:
+  pina-skill --install [DIR]
+  pina-skill --print-path
+  pina-skill --print-install
+  pina-skill --help
+
+Options:
+  --install [DIR]  Copy the skill to DIR. Defaults to the Codex skill directory.
+  --print-path     Print the packaged skill source directory.
+  --print-install  Print manual installation commands.
+  -h, --help       Show this help.
+
+The installer never overwrites an existing skill directory.`;
+}
+
+function main(arguments_ = process.argv.slice(2)) {
+	const command = arguments_[0];
+	if (command === "--print-path") {
+		console.log(packageRoot);
+		return 0;
+	}
+
+	if (command === "--print-install") {
+		const destination = defaultDestination();
+		console.log(`Packaged skill: ${packageRoot}`);
+		console.log(`Default destination: ${destination}`);
+		console.log("Install with: pina-skill --install");
+		return 0;
+	}
+
+	if (command === "--install") {
+		const requestedDestination = arguments_[1];
+		if (
+			arguments_.length > 2 ||
+			(requestedDestination !== undefined &&
+				requestedDestination.startsWith("--"))
+		) {
+			console.error("`--install` accepts at most one destination directory.");
+			return 2;
+		}
+
+		const destination = requestedDestination ?? defaultDestination();
+		console.log(`Installed Pina skill at ${installSkill(destination)}`);
+		return 0;
+	}
+
+	if (command === undefined || command === "--help" || command === "-h") {
+		console.log(helpText());
+		return 0;
+	}
+
+	console.error(`Unknown argument: ${command}`);
+	console.error("Run `pina-skill --help` for usage.");
+	return 2;
+}
+
+module.exports = {
+	defaultDestination,
+	helpText,
+	installSkill,
+	main,
+	packageRoot,
+};
+
+if (require.main === module) {
+	try {
+		process.exitCode = main();
+	} catch (error) {
+		console.error(error instanceof Error ? error.message : String(error));
+		process.exitCode = 1;
+	}
+}

package/package.json

@@ -1 +1,39 @@
-{"description":"Placeholder package for @pina-rs/skill","name":"@pina-rs/skill","repository":"https://github.com/pina-rs/pina","version":"0.0.0"}
+{
+	"name": "@pina-rs/skill",
+	"version": "0.10.0",
+	"description": "Agent skill for creating and maintaining secure Pina Solana programs",
+	"keywords": [
+		"agent",
+		"pina",
+		"pinocchio",
+		"skill",
+		"solana"
+	],
+	"homepage": "https://pina.rs",
+	"bugs": {
+		"url": "https://github.com/pina-rs/pina/issues"
+	},
+	"license": "Apache-2.0",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/pina-rs/pina.git",
+		"directory": "packages/pina__skill"
+	},
+	"bin": {
+		"pina-skill": "bin/pina-skill.cjs"
+	},
+	"files": [
+		"SKILL.md",
+		"README.md",
+		"agents",
+		"bin",
+		"references"
+	],
+	"publishConfig": {
+		"access": "public",
+		"provenance": true
+	},
+	"engines": {
+		"node": ">=18"
+	}
+}

package/references/cli-and-codegen.md

@@ -0,0 +1,191 @@
+# CLI and Code Generation
+
+## Discover commands from help
+
+The installed CLI is authoritative:
+
+```sh
+pina --help
+pina build --help
+pina generate --help
+pina idl --help
+pina idl generate --help
+pina idl fetch --help
+pina idl diff --help
+pina idl publish --help
+pina docs --help
+pina init --help
+pina test --help
+pina dev --help
+pina keys --help
+pina doctor --help
+pina completions --help
+pina profile --help
+pina deploy --help
+pina codama generate --help
+```
+
+Use `pina docs` to list bundled terminal topics. Custom topics can be supplied through `PINA_TEMPLATES_DIR` when a project maintains its own operational guidance.
+
+## Daily project workflow
+
+Run project-aware commands from the program directory or any descendant. Pina uses the nearest ancestor `Pina.toml`; an existing unambiguous Cargo package also works without configuration.
+
+```sh
+pina build
+pina test --unit
+pina test
+pina generate
+```
+
+`pina build` compiles SBF with the required `bpf-entrypoint` feature and refreshes the IDL. Pass program features explicitly when required:
+
+```sh
+pina build --features logs,cpi --no-default-features
+```
+
+The library target name determines the canonical outputs:
+
+```text
+<cargo-target>/deploy/<library-name>.so
+<cargo-target>/idl/<library-name>.json
+```
+
+`pina generate` refreshes that IDL and renders the client languages selected in `Pina.toml`. Override the selection for one run with repeatable `--client rust`, `--client typescript`, or `--client dart` flags. Generated ecosystem roots may be replaced, so keep hand-written code outside them.
+
+## Project diagnostics and identity
+
+Use the versioned diagnostic report before changing a project:
+
+```sh
+pina doctor --json
+pina keys show --json
+```
+
+`doctor --json` keeps stdout valid JSON and returns a failing exit status when required project or SBF prerequisites are unavailable. Its tool requirements follow the clients selected in `Pina.toml`.
+
+Treat program identity changes as security-sensitive. `pina keys sync` validates an existing Ed25519 keypair and updates exactly one parsed `declare_id!`. `pina keys new` creates a local identity; only `pina keys new --force` may rotate an existing one. Never copy or print keypair bytes. On platforms where Pina cannot guarantee private permissions, generate the keypair with trusted platform tooling and then run `pina keys sync --keypair <path>`.
+
+## Deterministic build artifacts
+
+Use the verified-build backend when you need a deterministic SBF artifact:
+
+```sh
+pina build --verify
+```
+
+This requires an exact `solana-verify 0.5.1` installation, a working Docker-compatible daemon, a root `Cargo.lock`, the generated Solana CLI workspace metadata, and a completely clean Git worktree. Pina does not install or update these prerequisites.
+
+The successful command prints the canonical `target/deploy` artifact, the generated IDL, a content-addressed SBF artifact, and its Pina-local build-record path. Keep the printed record and adjacent SBF together; consumers recompute the executable hash before trusting the record.
+
+`pina build --verify` creates deterministic build inputs and outputs. It does not compare the artifact with an on-chain program or record an on-chain verification result.
+
+## Testing and development
+
+Use `pina test --unit` for native/Mollusk tests and `pina test` for the generated SBF/Surfpool integration package under `tests/surfpool`. Cargo remains attached to the terminal in both modes. `pina dev` delegates persistent artifact watching and redeployment to Surfpool, which owns terminal input, output, errors, prompts, and Ctrl-C until it exits. Its default is offline, so select `--network` or `--rpc-url` only when remote state is required. Prefer a named network. Explicit RPC URLs must be credential-free HTTP(S) URLs with a host and no user information, query, fragment, or control character. They are visible in Surfpool's child-process arguments, so never put a secret anywhere in the host, path, or other URL text. On the first run, use `pina dev --yes`, then inspect and commit the `txtx.yml` runbook Surfpool creates.
+
+## IDL extraction
+
+Generate a Codama root-node document from a program crate. Bare invocation remains compatible; `generate` makes the operation explicit:
+
+```sh
+pina idl --path ./programs/counter_program --output ./idls/counter_program.json
+pina idl generate --path ./programs/counter_program --output ./idls/counter_program.json
+```
+
+Without `--output`, JSON is the only stdout content; progress and extraction counts go to stderr. This makes the command safe in pipelines:
+
+```sh
+pina idl --path ./programs/counter_program --compact | jq -e '.program'
+```
+
+Treat the IDL as a public contract. Review instruction, account, PDA, error, and type changes rather than accepting generated churn wholesale.
+
+## Canonical on-chain IDLs
+
+Network IDL operations always require an explicit cluster. Fetch the canonical direct, zlib-compressed UTF-8 Codama IDL under the fixed `idl` seed:
+
+```sh
+pina idl fetch --cluster devnet --program-id <PROGRAM_ADDRESS> --output ./idl.json
+pina idl diff --cluster devnet --program-id <PROGRAM_ADDRESS> --file ./idl.json
+```
+
+`diff` compares parsed JSON: object order and whitespace are ignored, but array order is preserved. Exit status `0` means equal, `2` means different, and `1` means the command failed.
+
+Direct publication requires the canonical upgrade-authority keypair and explicit confirmation (`--yes` in automation):
+
+```sh
+pina idl publish --cluster devnet --file ./idl.json \
+  --authority ~/.config/solana/upgrade-authority.json --yes
+```
+
+For review, multisig, or DAO signing, export every transaction the official planner requires without submitting any:
+
+```sh
+pina idl publish --cluster mainnet-beta --file ./idl.json \
+  --export <MULTISIG_ADDRESS> --output ./idl-plan.txt
+```
+
+Do not describe an export as one transaction. Preserve the complete upstream `[Transaction #N]` framing and order. An exported authority is a noop signer; do not combine `--export <ADDRESS>` with local authority or payer keypairs.
+
+## Repository-wide client generation
+
+Use the legacy Codama surface when a repository intentionally generates clients for several example programs in one command:
+
+```sh
+pina codama generate --examples-dir ./programs --idls-dir ./idls \
+  --rust-out ./clients/rust --js-out ./clients/js --dart-out ./clients/dart
+```
+
+Use repeatable `--example` filters for a focused run. Generated roots may be replaced; never store hand-written code inside them.
+
+Pina's generated clients preserve discriminator-first layouts and zeropod boundary checks. If a repository uses a custom renderer command, keep that command as the source of truth.
+
+## Static SBF profiling
+
+Profile a compiled shared object:
+
+```sh
+pina profile
+pina profile ./target/deploy/counter_program.so
+pina profile ./target/deploy/counter_program.so --json --output ./profile.json
+```
+
+When the path is omitted, Pina discovers `<cargo-target>/deploy/<library-name>.so`. The report is a static estimate, not a validator execution trace. Use it for deterministic comparisons and investigate material changes in context. Output files are written atomically and cannot alias the input binary through hardlinks or linked paths.
+
+# Verified deployments
+
+Use the content-addressed record produced by the deterministic build. Never invent or override its repository, revision, paths, library, or Cargo feature set.
+
+```bash
+pina build --verify
+pina verify check --program-id <ADDRESS> --cluster devnet
+pina verify record \
+  --program-id <ADDRESS> \
+  --cluster devnet \
+  --build-record ./target/pina/verifiable/my_program-<HASH>.json \
+  --authority ./upgrade-authority.json
+```
+
+`pina verify check` is read-only: it compares the local artifact with the deployed executable and returns exit code `2` for a completed hash mismatch. Do not retry that result as an infrastructure failure.
+
+`pina verify record` rebuilds the exact repository revision from the validated build record and writes verification metadata on-chain. Review the program, cluster, record, and authority before adding `--yes`; mainnet and unknown remote RPC origins additionally require `--acknowledge-mainnet`.
+
+Use `pina verify record --export [AUTHORITY] --output verification.tx` when another signer or multisig must submit the transaction. Export performs Pina's deployed-hash preflight but never submits or rebuilds the repository, does not require `--yes` or `--acknowledge-mainnet`, and writes only the validated base58 or base64 transaction payload. Remote verification begins only after the exported transaction is submitted.
+
+`pina verify submit --program-id <ADDRESS> --uploader <ADDRESS>` submits an existing record to the official mainnet remote verifier. `pina verify status --program-id <ADDRESS>` is the corresponding read-only mainnet status query. Never place credentials in an RPC URL; the URL is necessarily visible in child-process arguments.
+
+## Safe deployment
+
+Plan deployments before permitting a write:
+
+```sh
+pina deploy --cluster devnet \
+  --upgrade-authority ./keys/devnet-authority.json \
+  --payer ./keys/devnet-payer.json \
+  --dry-run --json
+```
+
+The cluster is always explicit. Pina never inherits a Solana CLI target or wallet, and deploy never creates a program identity. Conventional artifacts are `<cargo-target>/deploy/<library-name>.so` and `<cargo-target>/deploy/<library-name>-keypair.json`; override either path only when the plan requires it. Review the program ID and complete argument vector in the plan. Keep keypairs below 4 KiB and owner-private; on Unix use mode `0600`, while Windows ACLs must be restricted with operating-system tooling.
+
+Remote execution requires an interactive `deploy` confirmation or `--yes`. Named mainnet and custom remote endpoints also require `--allow-mainnet`. Custom URL user information, queries, and fragments are rejected, but accepted hosts and paths remain visible in plan output and process listings. Never put a secret anywhere in the URL; prefer a named cluster. Use `--build` when the canonical artifact must be refreshed before the final plan. Deployment requires the external Agave `solana` executable on `PATH`.

package/references/program-authoring.md

@@ -0,0 +1,63 @@
+# Program Authoring
+
+## Data and instruction types
+
+Use Pina's macros for their specific wire contracts:
+
+- `#[discriminator]` defines explicit discriminator bytes.
+- `#[account]` creates discriminator-first, validated zero-copy account storage.
+- `#[instruction]` creates typed instruction data with a discriminator-first wire layout.
+- `#[event]` creates typed event data.
+- `#[error]` maps program errors without an ad hoc conversion layer.
+- `#[pda]` defines PDA constructors and seed helpers.
+- `#[derive(Accounts)]` converts the ordered account slice into a typed instruction account set.
+
+Use explicit discriminator values. Reordering enum variants must not change existing wire values.
+
+Fixed-layout storage fields must satisfy zeropod's representation and validation rules. Use Pina's POD wrappers for numeric and boolean storage. Keep text and collections in bounded fixed-capacity representations with explicit length validation.
+
+## Account validation
+
+Validate before reading or mutating account data. A typical chain is:
+
+```rust
+account
+	.assert_signer()?
+	.assert_writable()?
+	.assert_owner(program_id)?;
+```
+
+Add address, program, sysvar, seed, emptiness, or type assertions when the instruction relies on them. Do not assume a typed cast proves ownership or that a signer proves authority over stored state.
+
+Important cases:
+
+- Check the invoked program's address before CPI.
+- Check an account is empty before initialization.
+- Check program ownership before changing its lamports.
+- Require writability before resize or mutation.
+- Validate the exact sysvar address before reading sysvar data.
+- Reject duplicate mutable aliases unless the instruction explicitly supports them.
+- Bind an authority signer to the authority stored in program state.
+
+## PDAs
+
+Use a stable, type-specific byte-string namespace as the first seed. Prefer canonical bump derivation and validation. Do not reuse one seed namespace for unrelated account types.
+
+Seed changes alter addresses. Treat them as migrations, not refactors.
+
+## Initialization, resize, and close
+
+Initialization must prove that the target is empty and that its derived address is correct before allocating or writing state. Resize operations must validate authority, owner, address, writability, and the requested bounds before changing data length.
+
+When closing an account, use the Pina close helper that matches the data-erasure requirement. Zero account data before transferring lamports when stale bytes must not remain observable.
+
+## Compatibility review
+
+Regenerate and inspect the IDL after changing:
+
+- a public account, instruction, event, error, or PDA declaration;
+- discriminator values;
+- field order, field type, or fixed capacity;
+- account ordering, signer/writable constraints, or known addresses.
+
+If a change moves bytes or addresses, state that explicitly and require the user's approval when it was not already part of the request.

package/references/project-setup.md

@@ -0,0 +1,69 @@
+# Project Setup
+
+## Prefer the scaffold
+
+Start a program with the installed CLI so the generated Pina version, feature names, target configuration, and starter code stay aligned:
+
+```sh
+pina init counter_program
+cd counter_program
+pina doctor
+pina keys show
+pina build
+pina test --unit
+pina test
+pina generate
+```
+
+The scaffold pins the nightly toolchain and `rust-src` needed by `pina build`; install its compatible linker with `cargo install sbpf-linker --version 0.1.8 --locked` before the first SBF build. TypeScript client generation also requires Node.js with npm and `npx`. Keep the generated `Pina.toml` as the project-local discovery and client-selection contract.
+
+Before deployment, establish the program identity explicitly. Use `pina keys new` for a fresh local identity or validate a keypair produced by trusted platform tooling with `pina keys sync --keypair <path>`. Never use `--force` unless the intended operation is an identity rotation.
+
+Use `pina init --help` before selecting a destination or replacing existing scaffold files. The command preserves existing files unless the user explicitly supplies `--force`; inspect the destination before using that flag.
+
+## Expected boundaries
+
+A Pina program should keep these concerns separate:
+
+- on-chain instruction processing and account types in a `no_std`-compatible library;
+- the SBF entrypoint behind the project's `bpf-entrypoint` feature;
+- host tests and VM fixtures in test-only modules or integration tests;
+- embedded Surfpool RPC tests in the isolated `tests/surfpool` Cargo package, separate from the fast native loop and SBF dependency graph;
+- IDL and generated clients outside hand-written program source.
+
+Do not add a general application framework, async runtime, serializer, or allocator to the on-chain path unless the program's requirements justify it.
+
+## Existing projects
+
+Before adding Pina to an existing crate, inspect its Rust edition, toolchain, Solana dependencies, target configuration, and entrypoint. Prefer the versions and features emitted by the same installed `pina` CLI that will maintain the project. Avoid copying dependency versions from an unrelated repository.
+
+The usual structure is:
+
+```rust
+#![cfg_attr(not(test), no_std)]
+
+use pina::prelude::*;
+
+nostd_entrypoint!(process_instruction);
+
+fn process_instruction(
+	program_id: &Address,
+	accounts: &mut [AccountView],
+	data: &[u8],
+) -> ProgramResult {
+	let instruction: ProgramInstruction = parse_instruction(program_id, &ID, data)?;
+
+	match instruction {
+		ProgramInstruction::Initialize => InitializeAccounts::try_from(accounts)?.process(data),
+	}
+}
+```
+
+Adapt names and dispatch arms to the program; do not introduce a generic router when a direct match remains clear.
+
+## Feature discipline
+
+- Keep `pina` default features off when the project uses an explicit minimal feature set.
+- Enable token or Token-2022 support only for programs that call those APIs.
+- Compile tests without the on-chain entrypoint when the project follows the common library-testing pattern.
+- Build the deployable program with the repository's pinned SBF toolchain and linker configuration.

package/references/testing.md

@@ -0,0 +1,69 @@
+# Testing and Verification
+
+## Choose the smallest useful layer
+
+- Pure parsing, arithmetic, and state-transition logic: ordinary Rust unit tests.
+- Account metadata, instruction execution, and expected `ProgramError` values: Mollusk or the project's established VM harness.
+- Entrypoint, deployment, linker, or serialized-program behavior: an SBF build plus an integration test.
+- Public macro or IDL changes: fixture tests and generated-artifact drift checks.
+- Layout or borrowing invariants: focused boundary tests; use Miri only when the repository already supports it or the task specifically warrants it.
+
+Test the rejected path as well as the successful path for authorization and validation changes. Verify that failed instructions leave relevant account data and lamports unchanged.
+
+## Baseline Cargo checks
+
+Use project task aliases when they exist. For a standalone project without them:
+
+```sh
+cargo test
+cargo build --all-features
+cargo clippy --all-features --all-targets
+```
+
+Format with the project's configured formatter. In the Pina repository, use `fix:format` or `dprint fmt`; do not invoke `rustfmt` directly.
+
+Run `pina doctor --json` when a failure may come from project discovery or a missing tool. Consume the exit status and typed check IDs; do not scrape the human report. Missing configured client tools, `sbpf-linker`, or nightly `-Z` support should be fixed before treating SBF or client-generation failures as code defects.
+
+For a project generated by the Pina CLI, preserve both supported loops:
+
+```sh
+pina test --unit # native Rust and Mollusk
+pina test        # real SBF artifact on an isolated Surfpool instance
+```
+
+Use `--filter <name>` for a focused run. Never describe `pina test --unit` as an SBF or RPC test.
+
+## SBF builds
+
+Prefer the project-aware build, which uses the discovered program, pinned toolchain, and Cargo target directory:
+
+```sh
+pina build
+```
+
+Use the equivalent low-level Cargo command only when diagnosing the compiler or linker invocation:
+
+```sh
+cargo build --release --target bpfel-unknown-none \
+  -p counter_program -Z build-std=core,alloc -F bpf-entrypoint
+```
+
+Do not silently skip an SBF-dependent test because the artifact is missing. Build it or report the missing prerequisite.
+
+Generated Surfpool tests use the embedded SDK with dynamic ports and explicit teardown. Cargo remains attached to the terminal so test output and interrupts behave normally. Use `pina dev` for a persistent foreground Surfnet; Surfpool owns terminal input, output, errors, prompts, and Ctrl-C for that lifecycle. It is offline unless the user explicitly selects a network or RPC URL. Prefer a named network. An explicit RPC URL must be credential-free HTTP(S) with a host and no user information, query, fragment, or control character. Because Surfpool receives it in child-process arguments, never place a secret anywhere in the URL, including its host or path. The first run requires `pina dev --yes`; inspect and commit the generated `txtx.yml` before ordinary development. Do not replace either workflow with a fixed-port daemon and a readiness sleep.
+
+## Generated contracts
+
+After a public program-surface change:
+
+1. Generate the IDL.
+2. Validate the JSON.
+3. Regenerate each committed client target.
+4. Type-check or compile generated clients.
+5. Fail on unreviewed drift.
+
+Counts are useful guardrails: declared instructions, accounts, and errors should match their generated IDL counterparts.
+
+## Release checks
+
+Follow the repository's release policy. When it uses changesets, add release intent for publishable code or package changes and validate the release metadata before handoff. Do not publish, tag, or open a release request unless the user explicitly authorizes that external action.

package/CHANGELOG.md

@@ -1,3 +0,0 @@
-## 0.0.0
-
-- Placeholder release.

package/LICENSE

@@ -1 +0,0 @@
-Placeholder package published by monochange. See the source repository for license terms.