- commit
- 47ada2bd81e75ba14b7e81912b5d7780e58babc9
- parent
- d14c5178f9876fc17e80c89129e7317663861dcf
- author
- Dami <dami.etoile@gmail.com>
| A | agent/ | 122 | ++++++++++++++++++++++++++++++ |
| A | agent/ | 4 | + |
@@ -0,0 +1,122 @@
1+---2+name: nzip3+description: Set up, diagnose, and use the nzip HTML sharing CLI with repository-local working directories and safe publishing defaults. Use when installing or authenticating nzip, troubleshooting nzip access, publishing a plan, design, report, prototype, or other HTML artifact, managing an existing nzip site, or establishing nzip conventions in a repository.4+---5+6+# nzip7+8+Use nzip to publish HTML while keeping the editable source beside the repository context that9+produced it. Diagnose the local installation before guessing about unavailable access.10+11+## Setup12+13+1. Locate the repository root with `git rev-parse --show-toplevel` when inside a Git repository.14+2. Check for the CLI with `command -v nzip` and `nzip --help`.15+3. If it is missing and Deno is available, install or upgrade it:16+17+ ```sh18+ deno install -g -A -f -n nzip jsr:@nzip/cli19+ ```20+21+4. Authenticate only with a server and token supplied by the user or environment:22+23+ ```sh24+ nzip auth --server <url> --token <token>25+ ```26+27+ Omit `--token` when an interactive prompt is safer. The prompt requires a TTY: in a28+ non-interactive run, omitting `--token` fails instead of prompting, so ask the user to run29+ `nzip auth` themselves. Never print, commit, or invent the token.30+31+5. Ensure the repository `.gitignore` contains this exact rule:32+33+ ```gitignore34+ .nzip-*-plan/35+ ```36+37+ Add the rule without replacing existing ignore entries. Put generated sites at the repository38+ root using a descriptive name such as `.nzip-auth-plan/` or `.nzip-api-design-plan/`. Keep the39+ directory after publishing so later revisions retain the originating repository context, but do40+ not commit it.41+42+## Doctor43+44+Run checks in this order and stop at the first failure that needs user input:45+46+1. `command -v nzip` — if missing, follow Setup.47+2. `nzip --help` — confirm the installed command starts.48+3. `nzip status --json` — verify saved authentication, server reachability, and token validity.49+4. `nzip vault ls --json` — verify available vaults and the default vault.50+51+Use the JSON `error` and `hint` fields as the primary diagnosis. Re-run `nzip auth` for missing or52+rejected credentials, correct the configured server for reachability failures, and ask the user to53+choose a vault when no safe destination is evident. Respect `allowVaults`; never bypass it with a54+raw address. Ask to use the required network or filesystem permissions when a sandbox blocks a55+check instead of reporting nzip as broken.56+57+## Publish an artifact58+59+1. Create a complete site inside `.nzip-<purpose>-plan/` at the repository root. Use `index.html`60+ as its entry point and keep any related assets inside the same directory.61+2. Validate the artifact locally in proportion to its complexity.62+3. Publish with an explicit low TTL:63+64+ ```sh65+ nzip push .nzip-<purpose>-plan/ --ttl 1d66+ ```67+68+ Use `1d` for plans, designs, review pages, and other disposable agent artifacts unless the user69+ requests a different review window. Choose a longer finite TTL only when the requested workflow70+ plainly needs it. Do not use `forever` by default. The nzip service default is 14 days, so always71+ pass `--ttl 1d` for these short-lived artifacts rather than relying on omission.72+73+4. Use an explicit `<vault>:<alias>` target when the destination matters, picking a vault from74+ `nzip vault ls --json`:75+76+ ```sh77+ nzip push .nzip-<purpose>-plan/ <vault>:<alias> --ttl 1d78+ ```79+80+5. Return the canonical URL and expiry. If the user requested a review boundary or asked for only81+ the link, return only the link and wait for approval before implementing the reviewed work.82+83+## Use guide84+85+Prefer `--json` when consuming command output programmatically.86+87+- Inspect readiness: `nzip status --json`88+- List destinations: `nzip vault ls --json`89+- Register a vault: `nzip vault add <name> [--slot N] [--description TEXT]`90+- Rename or describe a vault: `nzip vault update <name> [--name NEW_NAME] [--description TEXT]`91+- Set the default vault: `nzip vault default <name>`92+- List sites: `nzip ls [vault] --json`93+- Inspect a site: `nzip site <target> --json`94+- Publish or update: `nzip push <dir|file> [target] --ttl <days>`95+- Find its local source: `nzip where <target> --json`96+- Recover hosted source: `nzip cp <target> [dir]`97+- Change retention: `nzip site <target> --ttl <days>`98+- Set or remove a password: `nzip site <target> --password <pw>` / `--no-password`99+- Review history: `nzip revert <target> --list --json`100+- Restore history: `nzip revert <target> --to <push-number>`101+- Delete only on explicit request: `nzip rm <target> --yes`102+103+Use password protection when the content or user requires it; `nzip push` accepts the same104+`--password <pw> | --no-password` flags to set it at publish time. Vault descriptions appear in105+`vault ls` and `status`; use them to pick the right destination, and pass an empty `--description`106+to clear one. A vault rename updates the invoking client's default vault and allow-list, but other107+clients keep the old name. Treat `revert`, vault renames, password changes, TTL changes, and108+deletion as state changes; do not perform them while merely diagnosing. Never infer deletion109+confirmation.110+111+## Sane defaults112+113+- Keep generated HTML in `.nzip-<purpose>-plan/`, not a system temp directory or a tracked source114+ directory, unless requested.115+- Ignore all such directories with `.nzip-*-plan/`.116+- Publish disposable plans and designs with `--ttl 1d`.117+- Prefer finite TTLs; use `forever` only when explicitly requested.118+- Prefer descriptive aliases and an explicit vault when identity or audience matters.119+- Preserve the local plan directory for iteration and `nzip where`; do not commit it.120+- Use complete, self-contained HTML and relative asset paths.121+- Use read-only status, list, and inspect operations before mutations when destination state is122+ uncertain.