# PostPlus Agent Install Guide

The following steps are designed for AI agents. Some steps require user interaction in the browser.

The goal is to install the matching CLI and skills, then continue the user's
chosen task. Authenticate only when that task requires an account.

## Installation responsibility

PostPlus manages its own Node runtime. Do not require the user to inspect,
upgrade, remove, or choose a system Node/npm version. Use the official installer
below even if the environment has no Node or an older npm-installed PostPlus
cannot start. The installer selects and verifies the approved program/runtime
combination without replacing system Node.

## Step 1: Prepare PostPlus and Its Skills

If a managed PostPlus installation already works, inspect it with
`postplus status --json` and use `postplus update --json` when maintenance is
needed. Do not reinstall merely because the user started a different session.

For first installation or migration from a broken old npm installation, run the
appropriate official entry. Global skills are the default. Use project scope
only if the user requested it; do not ask them to choose internal setup details.

macOS / Linux:

```sh
setup_dir=$(mktemp -d) || exit 1
trap 'rm -rf "$setup_dir"' EXIT
curl --fail --silent --show-error --location --proto '=https' --proto-redir '=https' https://postplus.io/install.sh -o "$setup_dir/install.sh" &&
sh "$setup_dir/install.sh"
```

For project scope, run from that project and append `--current-directory` to
the final installer command.

Windows PowerShell:

```powershell
$setupFile = Join-Path ([IO.Path]::GetTempPath()) ('postplus-' + [Guid]::NewGuid().ToString('N') + '.ps1')
try {
  Invoke-WebRequest https://postplus.io/install.ps1 -OutFile $setupFile -UseBasicParsing
  powershell.exe -NoProfile -ExecutionPolicy Bypass -File $setupFile
  if ($LASTEXITCODE -ne 0) { throw 'PostPlus installation did not complete.' }
} finally { Remove-Item -LiteralPath $setupFile -Force -ErrorAction SilentlyContinue }
```

For project scope, run from that project and append `-CurrentDirectory` to
the installer invocation.

## Waiting and Failure Diagnostics

A tool returning a running process/session handle is not an installation failure.
Use that host's supported poll/resume mechanism until the process exits. Do not
kill a still-running installation merely because a 120-second tool wait ends:
a component download may allow 20 seconds to connect and 300 seconds total,
and a complete installation can contain several downloads. Respect the actual
installer deadline and user cancellation. If the host has a hard execution limit
that cannot be continued, report an external interruption and unknown installation
state; do not call it a confirmed server or TLS failure or launch a duplicate process.

On failure, preserve the CLI's structured error and its bounded, redacted cause
in a copyable diagnostic summary. Include operation, component, stage, platform
and architecture, available current/target versions, original and effective target
host/path, original error code, HTTP status, elapsed time and configured timeout
when reported; mark unavailable facts as unknown. Preserve the error's next action
and recovery state instead of reducing it to "cannot connect to service".
A curl 28 means an operation timeout; it alone does not establish TLS handshake
failure. Distinguish DNS, connection, certificate, HTTP, transfer, checksum,
extraction and permissions only when the returned evidence supports that diagnosis.
Never include authentication headers, proxy credentials, signed URL query strings,
raw response bodies or private local paths in a shareable summary.

Offer a bounded read-only connectivity check for the reported download host in
the same Agent execution environment, keeping certificate verification enabled.
For a public, unsigned download URL, a HEAD request with a short connection and
total timeout can check that hop; it does not prove a complete download or checksum.
Do not replay signed URLs or expose their query strings. Browser access or another
terminal is not proof of connectivity in this environment. The website, Node
runtime host and GitHub release asset host are distinct download steps. Report
proxy configuration only as configured/unconfigured and supported/unsupported.
Do not change proxy settings, download sources, certificate checks or retry policy.

If the cause remains unknown, collect only the Agent/OS and available PostPlus
version, redacted original failure output, and same-environment check result.
Keep the user's original task in the handoff; explain what is blocked and the
next action without claiming the installation, update or original task completed.
Do not repeat paid work or start another automatic recovery after an exhausted one.

## Step 2: Read the Verified Result and Continue

The installer prepares both the CLI and its matching skills. Do not invoke a
separate skills installer or repeat setup after a successful result.

Read the JSON result. Continue only when `ok` and `diskReady` are true.
Use `installation.commandPath` as the executable for subsequent commands in
this Agent session: changing a child process cannot update the parent shell's
PATH. New shells receive the registered PostPlus command path. Preserve this
path in any task handoff; do not select an older npm command accidentally.

On first installation, use the returned official introduction to explain what
PostPlus is and how it can help, in the user's language. Retain concrete social
and advertising platform examples and applicable account restrictions. If the
user has shared a business or goal, make the introduction relevant to it;
otherwise invite them to describe what they want to promote. Avoid internal CLI,
runtime, or skill terminology and do not merely announce installation success.
Include the advertising strategy library count and URL from the official
introduction as an addition to the existing product overview.

After a real update, briefly explain what changed and why it helps the user,
using the official releaseNotes returned by the successful update. For automatic
updates, use the official update title and summary reported on stderr. Mention
the strategy library count and URL when present in those release notes, along
with relevant account restrictions, then continue the original task in the current
conversation. Do not repeat the full product introduction, invent
changes when no release notes are returned, or announce success after a failed
update. An already-current installation needs no repeated update introduction.

Disk readiness does not prove this session has read the updated skills. Read the
current task's installed Skill instructions and needed references, then continue
in this conversation. Do not ask the user to open a new conversation or copy the
original request. An unchanged installation needs no repeated setup.

If the installer specifically reports a damaged PostPlus runtime, program, or
installation record, make one repair attempt using the same official installer
with `--repair` (macOS/Linux) or `-Repair` (Windows), preserving the requested
scope. Repair verifies a fresh copy before switching and preserves user
configuration. If repair fails, stop and report its exact error and next action.
Do not use repair for network, permission, or ordinary task failures.

For other setup failures, report the specific installation failure and next action.
Do not run an unlimited retry loop, request a system Node upgrade, delete the
old npm installation, or request administrator access as a workaround. Network,
filesystem, unsupported-platform and execution-policy restrictions must be
reported as environment restrictions, not unexplained Node version errors.

## Step 3: Sign In When Requested

Skip this step for local tasks that do not require an account. When the chosen
task reports missing authentication, use:

```bash
postplus auth login
```

Share the exact authorization URL as a clickable link so the user can Connect
in their browser. Wait for the CLI to confirm success before continuing. Never
approve the browser connection on the user's behalf or restart a cancelled or
expired login automatically.

## Step 4: Start With The User's Goal

Installation already verifies skill content. Do not add routine diagnostic
commands before starting a task. For a known task, read only its matching skill.
If the user is exploring what to do, read `postplus list --json` once: its
categories, descriptions, and examples describe the installed capabilities.
Ask one useful question about the desired result when the goal is unclear,
then read the selected skill; do not open every skill to compare them.

Use `postplus skills verify` to investigate installed content and
`postplus status` to investigate installation or account state when needed.
Neither command refreshes the running agent session.

## Maintenance And Blocked Commands

Use `postplus update` for maintenance in the intended scope. It does not
require login. When the CLI already attempted automatic recovery, do not start
another update. Otherwise make at most one update attempt.

There is one repair exception for old installations: if maintenance reports
`Managed artifact integrity verification failed. Run the official installer to repair it.`,
make one official installer repair attempt using Step 1 with `--repair`
(macOS/Linux) or `-Repair` (Windows), preserving the intended scope. This repair
is allowed after a failed update; it is not another update attempt. Follow Step 2
and continue the original task only after the repair returns `ok` and
`diskReady` as true. If repair fails, stop and report its exact error and next
action; do not repeat repair or retry the original task. Do not use this exception
for network, permission, ordinary task failures, or an exhausted repair.

For every other maintenance failure, stop and report its exact error and next
action. Do not guess flags, inspect code to bypass the failure, or retry the
original task after failed maintenance.

If the CLI requests approval, explain the required decision and wait for the
user. Do not create a pseudo-terminal (PTY), pipe confirmation input, or confirm
on the user's behalf. Use the exact scoped action reported by the CLI only after
the user has explicitly authorized that replacement; an action or `--yes` is
not blanket permission. Never resubmit uncertain paid work or repeat exhausted
recovery. Do not reinstall for ordinary task failures.

## Completion

After successful installation or maintenance, read updated instructions needed
for the original task and continue in this conversation. The CLI verifies disk
content; the agent reads those instructions without discarding the user's task
or existing authorization. Do not hand the task back as a copyable prompt or ask
the user to start another conversation. Follow the reported action if maintenance
fails; an unchanged installation needs no repeated setup.

For "what can PostPlus do?" show the relevant capabilities from the installed
catalog in plain language; users can also run `postplus list` themselves.
Do not maintain a separate capability list or load a shared routing skill.
After maintenance, continue the original task instead of repeating discovery
or onboarding. This guidance does not authorize paid calls or publishing.