@hireobi/cli 0.0.0-stage → 0.1.7

package/skills/obi/references/outcomes.md

@@ -0,0 +1,70 @@
+# Recording and revisiting actual outcomes
+
+Use only outcome operations advertised by `capabilities`. Public-company
+evaluations are read-only for outcomes: researching a company does not prove
+the operator implemented changes there. Actual implementation observations
+belong to the connected business owner's account.
+
+## Read before a write or conclusion
+
+```bash
+obi harness outcomes --task-id <saved-task-UUID> --json
+obi harness outcomes --task-id <saved-task-UUID> --cursor <nextCursor> --json
+```
+
+Preserve the same task and any selected evaluation scope on every read. The
+response supplies total, truncated and nextCursor: follow all pages needed for
+the decision; a bounded strategy-context preview is not the whole journal.
+
+Read after a lost write response before retrying. Reuse the exact file and
+replay UUID for an identical observation; a changed payload needs a new UUID.
+An unknown task or missing server capability requires a specific recovery, not
+a hosted fallback or an invented successful save.
+
+## Implementation, publication and follow-up are separate
+
+After the customer confirms what actually changed and when, save a local
+implementation record and submit it with `obi harness observe --input <file>
+--json`. Its shape is:
+
+```json
+{
+  "schemaVersion": 1,
+  "taskId": "<saved-task-UUID>",
+  "replayKey": "<new-UUID>",
+  "kind": "implementation",
+  "implementedAt": "<confirmed-ISO-timestamp>",
+  "ownerConfirmed": true,
+  "summary": "<customer-confirmed change>",
+  "targetUrl": "<actual same-site URL, or null>"
+}
+```
+
+The returned observation ID binds later observations. An approved proposal or
+local draft is not implementation. Save only the minimum authorized customer
+material; private context does not become a cross-customer learning example.
+
+Publication uses `kind: "publication"`, the same task, a new replay UUID,
+`implementationEventId`, `actualUrl`, `confirmedAt`, and a fresh acquired
+`pageObservation` plus matching `parsedPage`. Use the public-page acquisition
+contract from [host work](host-work.md); pass the actual complete observation
+and parsed page, not a model-written claim that the URL is live. Include
+`artifactRevisionVersion` and `expectedText` only for a real saved revision;
+otherwise both are null. Do not invent an artifact revision for host-produced
+work. The server validates the record and distinguishes host-supplied HTTP
+evidence from indexing, rendered visibility and actual provider access.
+
+A follow-up uses `kind: "follow_up"`, the same task and
+`implementationEventId`, a new replay UUID and the UUID of a later server-stored
+`scanRunId`. The server derives the comparison from recorded measurements.
+Historical actions can be followed after later scans. Incompatible question
+versions, markets, engines or timing return a non-comparable or insufficient
+evidence result rather than a made-up lift. The observation does not start a
+new scan.
+
+Before presenting an effect, inspect the saved comparison, missing cells,
+concurrent changes and baseline. Separate a client report, verified HTTP
+content, a measured answer change and a causal explanation. Saved observations
+inform the next strategy context; general method promotion remains reviewed
+and evaluated separately. Recording observations never executes a task,
+publishes content, changes its paid status or consumes credits.

package/skills/obi/references/purchase.md

@@ -0,0 +1,89 @@
+# Buying paid packs
+
+Read when the customer wants to buy packs or change the packs or engines of a paid plan, and before proposing a change yourself. Buying happens in this conversation, where the customer reviews the questions each pack will measure; the `/billing` page shows the plan and keeps cards, invoices and cancellation. Every price you show comes from the server's quote response.
+
+Only the owner of the connected business account buys, with a verified email; a public-company evaluation case cannot.
+
+## What the customer decides
+
+| Decision | Where it comes from |
+|---|---|
+| How many packs | Each pack measures 25 reviewed questions; the customer picks the number from the buying situations they want covered. |
+| Optional engines | Claude and Perplexity each measure 1 to 10 distinct questions per pack, chosen among those marked `buyingEligible`. Propose only genuine buying questions, however few. |
+| The questions | The full reviewed set, written as in [questions](questions.md#writing-the-questions). |
+| The monthly amount | The quote's `monthlyAmountCents`, shown before any payment step. |
+
+## From review to active coverage
+
+1. **Review the portfolio.** Run `obi harness show --stage questions --packs <N> --json` and submit exactly `data.context.purchaseReview.questionCount` questions with `result.intendedPacks`, as [host work](host-work.md) describes. The customer reviews them; active coverage stays unchanged until payment. Then `obi questions show --json` gives `data.candidate.id` and `data.candidate.version`, which identify the reviewed set.
+2. **Quote.** Write one local file and keep it for every later step, copying the actual IDs and version:
+
+   ```json
+   {
+     "quoteId": "<new UUID kept for this exact basket>",
+     "basket": {
+       "catalogVersion": "obi-cli-dollar-v2",
+       "packs": 1,
+       "claude": true,
+       "perplexity": false,
+       "candidateSetId": "<data.candidate.id>",
+       "candidateVersion": 3,
+       "coreQuestionIds": ["<every question ID of the reviewed set: 25 per pack>"],
+       "claudeQuestionIds": ["<1 to 10 buying question IDs per pack>"],
+       "perplexityQuestionIds": []
+     }
+   }
+   ```
+
+   An engine set to `false` has an empty ID list. Run `obi harness purchase quote --input <file> --json`: it validates the basket against the current reviewed set and charges nothing. Show the customer the monthly amount, the packs, the engines and the questions each engine measures. Keep `scanBudget` out of the price, as [questions](questions.md) explains.
+3. **Prepare checkout, on the customer's explicit yes to that quote.** Run `obi harness purchase prepare --input <same file> --confirm-checkout --json`. It freezes the quote for 30 minutes (`expiresAt`) and opens `/billing` in the customer's browser (`browserUrl`; when `browserOpened` is false, give them the link). They open checkout there within that window and pay. Paid coverage starts only after verified payment.
+4. **Follow and resume.** `obi harness purchase status --json` reports `activationState`:
+
+   | `activationState` | Meaning and next step |
+   |---|---|
+   | `awaiting_payment` | Payment is not recorded yet; the customer finishes it on `/billing`. |
+   | `scope_activation_required` | Payment is recorded and the reviewed questions are not active yet. With `nextAction.kind` `resume_quoted_scope`, write a file holding only `{"quoteId": "<same UUID>"}` and run `obi harness purchase resume --input <that file> --json`. With `review_quoted_dependencies`, show `blockedReasons`, bring the Business review or the questions current with the customer, then resume. |
+   | `active` | The paid scope is active, and Obi starts a scan of the whole paid portfolio by itself within the hour: show the new coverage from `obi harness coverage --json` and that scan's state from `obi questions show --json`. |
+
+## Changing a paid plan
+
+A customer with paid packs changes them with `obi harness purchase change`; a first purchase uses the steps above.
+
+1. Review the new portfolio as in step 1, with the new pack count: write the added questions for an increase; for a reduction, keep the questions with the strongest evidence and priorities. The customer reviews the full set.
+2. Write the quote file of step 2 for the new plan and run `obi harness purchase change --input <file> --json`. The preview charges nothing:
+
+   | `kind` | What to show |
+   |---|---|
+   | `increase` | `amountDueCents`, charged now to the card on file and prorated to the renewal, then the new `quote.monthlyAmountCents`. |
+   | `reduction` | No charge now; the new monthly amount from `effectiveAt`, the renewal, with the current coverage kept until then. |
+
+3. On the customer's explicit yes to that amount, before `expiresAt`, run the same command with `--confirm-change`. Its `outcome`:
+
+   | `outcome` | Next step |
+   |---|---|
+   | `applied` | The new questions activate once the payment is recorded: follow `purchase status` and resume as in step 4. |
+   | `scheduled` | The reduction applies at `effectiveAt`. |
+   | `payment_confirmation_required` | Their bank asks for a confirmation on `/billing` (`browserUrl`); the increase applies once it is confirmed. |
+   | `preview_changed` | Nothing was charged: show the new `amountDueCents` and ask again. |
+
+A change that adds and removes at once (`PLAN_CHANGE_TWO_STEPS`) runs in two steps, each with its own yes: the increase first, then the reduction once the increase is applied. Only Obi support undoes a scheduled reduction: give the customer support@hireobi.com.
+
+## Proposing a change yourself
+
+When evidence shows a gap the plan does not measure, such as a buying situation outside the reviewed questions or a rival cited on questions the plan leaves out, propose the change once, with that evidence and the price from a quote or preview. After a no, raise it again only on new evidence.
+
+## What waits for the customer
+
+- Checkout preparation: their explicit yes to the displayed quote.
+- A plan change: their explicit yes to the previewed amount and date.
+- Payment: made by the customer on `/billing`; card details stay in that page.
+- Any other basket: changed packs, engines or questions get a new quote, a new UUID and their review.
+
+## Recovering
+
+- A lost response on `prepare` or `resume`: read `purchase status` first, then retry the exact same file and UUID; `resume` never starts another checkout.
+- A refusal because the reviewed questions changed before `prepare`: read `questions show` again and quote the current set with a new UUID.
+- After `prepare`, the open checkout keeps its quote, and `prepare` with another basket or UUID is refused until the customer closes that checkout in their browser or its 30 minutes pass. Then read `questions show` again and quote the current set with a new UUID.
+- An existing paid subscription makes `prepare` fail with `PURCHASE_CONFLICT`: change its plan with `purchase change`.
+- A `PLAN_CHANGE_*` refusal carries its next step in `nextAction`: an expired preview needs a new quote UUID, an uncertain outcome needs `purchase status` before any retry, and a refused payment leaves the plan unchanged.
+- `PURCHASE_CONFLICT` on `resume`: keep the quote UUID and any recorded payment, read status again, confirm the current Business review and Readiness, and review the questions before retrying.

package/skills/obi/references/questions.md

@@ -0,0 +1,40 @@
+# Buyer questions, scan and priorities
+
+After the business review is confirmed, inspect `obi harness show --stage questions --json`. Show the supported measurement markets and confirmed buyer audiences from its work context. Ask the customer to choose one market and one primary audience; a suggested market is guidance, not consent or a default. Prepare the displayed coverage count in the host and save it with the versioned `harness submit --stage questions --input <file> --json` path described in [host work](host-work.md). `obi questions show --json` reads the accepted set and its preparation state. A queued or running state means wait and inspect again after meaningful progress; do not announce that questions already exist.
+
+## Writing the questions
+
+A question is the prompt a real buyer types into ChatGPT, Claude, Gemini or Perplexity while deciding what to buy. The scan measures what those engines answer to it, so a generic question measures a market nobody is in. Follow `data.context.method` and the customer's saved memory (`obi memory list --json`) in this order:
+
+1. Read everything Obi learned before writing a word: run the command in `data.context.evidence.read` (one file with every persisted fact: offer, prices, use cases, integrations, objections, proof, competitor positioning, quoted buyer vocabulary). Split the file among subagents when the host offers them; each returns the facts that matter for one awareness stage. When `data.context.evidence` is null (a business read before the harness existed), the facts are the review's own citations in `data.allowedSourceRefs`: read them through `business show` and cite those.
+2. Write from the selected buyer's seat: their job, the situation that triggers the search, the constraint they state (budget, country, stack, team size, compliance), in the words the pages quote from them. Cite the claim IDs you used in `sourceRefs`; the audience claim alone is refused.
+3. Cover the awareness stages across the set: unaware of the category, aware of the problem, comparing solution types, evaluating this kind of product, choosing between named options. Spread the six intents.
+4. Shape each question like a chat prompt: first person, one ask, 8 to 30 words, a concrete situation, no adjectives copied from marketing pages. "Best AI gateway?" is a search query; "We are three developers shipping a Django app and need one API for several model providers with EU hosting, what should we use?" is a buyer prompt.
+5. Keep most questions unbranded. The server refuses a set where more than the published share (`data.context.method.limits.brandedShare`) name the company or a rival; comparison and alternatives intents use that allowance.
+6. Start most questions from the buyer's broad problem, where the company competes with other kinds of solutions. A buyer who already knows the company's niche wording is already looking for it. Use the deduced angles the customer confirmed (for example, migrating away from a named rival).
+7. Leave out what the buyer does not search for: the product's form factor (CLI, API, MCP) unless the buyer's stated job requires it, and the country unless it changes the answer (compliance, local data, currency). The scan already runs in the selected market.
+8. Name a specific tool only when the evidence, the customer's harness or the customer's answer supports it (for example, their CRM).
+
+### Buyer profiles and the cold/context pairs
+
+A real buyer asks with their chat memory on: the engine already knows their tools and constraints. Measure that effect with pairs:
+
+- Write three to five profiles from the personas of the primary ICP ([ICP and personas](business-judgment.md#icp-and-personas)). A profile is one first-person paragraph that describes one person as their assistant's memory would know them: role, company, the tools that matter for this target (one per slot, never two), and their situation or constraint. Vary the profiles where real buyers vary. "As a GTM engineer" alone is not a profile. Cite each profile's facts in its `sourceRefs`: published claim IDs, or the IDs of customer memory entries (`obi memory list --json`) that recorded the customer's confirmed answers.
+- For each pair, set `arm: "cold"` on the bare question and `arm: "context"` on its twin, with the same `pairId`. The twin's `text` is the profile text, one space, then the cold text, unchanged. Attach the profile (`id`, `text`, `sourceRefs`) to the context question; the cold question has `profile: null`.
+- Spread the profiles across pairs so that each profile covers several intents. Every question of a paired set belongs to a pair, so the count must be even.
+- A set must carry three to five distinct profiles; the server refuses fewer or more. Changing the layout of a paired set (adding, dropping or re-planning pairs or profiles) is reclassified as a new portfolio, not an edit. A wording edit of an existing pair keeps its arm, pair ID and profile ID.
+- When reading results, compare each pair's two arms on the same engine: the brands named, the company's presence and the rivals' presence. The difference is what the buyer's memory changes. The `arm`, `pairId` and `profile` of each question are in `harness show --stage questions` under `context.currentCandidate.questions`.
+
+Show the customer five representative questions with the fact each one came from, then the full set on request. The customer judges the voice; the server only checks that each question cites a fact beyond the audience and that the branded share holds.
+
+When Business corrections change the buyer or served market, reread its accepted review and fresh questions context before drafting. Resolve the selected measurement market and primary audience against that context, retaining corrected source references. Preserve unaffected accepted work; old questions remain visibly based on the earlier Business version until their replacement is accepted.
+
+Show the actual saved count, mix and representative wording, and offer the full set. The customer can correct a question in ordinary language. For the harness alpha, read the latest questions work and edit the full `context.currentCandidate.questions` array using the customer's wording; preserve its IDs, intents, facets, selected market, primary audience and source references. Submit it as a new versioned questions result. Read `questions show` after acceptance; a failed or stale submission leaves the prior version distinct. The older `questions edit` route is unavailable for this grant because it launches server reasoning.
+
+For a paid pack, Obi starts this scan by itself within the hour after the paid scope becomes active, by a purchase or a paid increase, and starts a failed one again: read `questions show` for its state instead of asking for an authorization; `questions proceed` would only replay it. When `questions show` still shows no scan of the paid scope an hour after it became active, and before any other `questions proceed`, read `harness coverage` and show the selected question and engine coverage, its cell count and whether `budgetQuote.completeCoverageAuthorized` is true. The USD values in `scanBudget` and `budgetQuote` are internal supplier spend limits, not a customer price. If full coverage is not authorized, obtain a reviewed budget grant before proceeding; a question edit cannot fix that error. Ask for the one scan authorization. Only an explicit yes runs `questions proceed --candidate-version <displayed version> --confirm-scan --json`. A retry after timeout begins with `questions show`; never replay a paid scan blindly. A customer subset does not mean every question was measured on every optional engine. A founder evaluation may have a separate authorized five-engine plan; use the displayed plan rather than an assumed count.
+
+`questions results --json` contains independently measured answers, timestamps, engines and citations. Show completed and missing cells plainly.
+It reads the latest completed scan, named in `run`; `runs` lists the customer's scans newest first, and `questions results --run <id> --json` (or `--run first`) reads one of them; a long scan pages, and `evidencePreview.fullEvidenceCommand` names the `--from` command for the same run's next questions. Compare two weeks only on cells both runs scored; an engine whose `status` is `partial` or `failed`, and each question's `gaps`, are planned cells without a scored answer: report them as missing evidence and leave them out of mention and citation rates. Acquire relevant cited or retrieved public sources before judging whether a factual claim is outdated. The host's answer to a question is a suggestion, never a measured result.
+`aggregates` gives that run's share of voice, leaderboard and most cited domains from the scorer: each percentage is a share of its `denominator.answersN` answers, which leaves out refusals and the `ungroundedN` answers given without a web search. Quote the denominator with every percentage, and when comparing weeks quote both, since they differ.
+
+After a completed scan, inspect `obi harness show --stage business --json` again. If it offers new scoped work after confirmation, acquire the relevant scan-cited media and any requested own or rival refresh; submit sourced observations before reasoning over strategies. This work does not reopen the already confirmed Business review. Then inspect `obi harness show --stage strategies --json`. Compare measured gaps with the saved business facts, acquired own/rival/media page facts, Readiness findings and user feedback. `questions results` may display a bounded `evidencePreview`; its listed questions and 500-character excerpts are not the full answer set. Use `harness evidence --work-id <UUID> --kind claims --query <gap> --json` for persisted facts, sections for quote context and `--kind measurements` for the pinned selected scan. Page through `nextCursor` and reconstruct the full answer and source references from their offsets before claiming a complete trace. Do not treat the compact work context as the whole corpus. Save supported ranked priorities with `harness submit --stage strategies --input <file> --json`, then read `obi strategies --json`. Rank by urgency × buyer importance first, then evidence, speed and effort; the three selected actions are the ones the customer should start this week, each with the observation it rests on (`evidenceRefs`: a measured question, a readiness failure, a page fact) and, when present, its `evidenceLevel`: say the level, its basis and how the customer verifies the result, and never call an action proven. Show the three, then the `considered` list the server returns: what was weighed and why it ranks lower. When the customer asks for more, present the next candidates from that list with their evidence; when the list is exhausted, say so and name the observation (a new scan, an implemented action, a widened reading scope) that would produce new candidates. If a strategy work unit is still awaiting the harness, report that state and resume it when the customer returns. If evidence supports fewer than three distinct actions, explain the gap rather than padding the list. Keep rejected actions in the considered set and change them only when new evidence warrants it. A recommendation is not a published asset; local briefs or drafts need customer review.