{ "id": "poc-guide-pack-r1", "title": "PoC Guide: plan, run, evaluate and close", "summary": "Choose one evaluation question, follow a supported route, compare the evidence with your criteria, then close costs, resources and open issues.", "audience": "PoC owners, first-time reviewers and already authorized operators", "version": "R1", "delivery_type": "documentation", "status": "documentation-review-edition", "outcomes": [ "An agreed PoC plan and named owners", "Understanding of one retained actual Work and its report", "For eligible operators only: a same-Work evidence checklist", "Explicit human review and resource-retention decisions" ], "prerequisites": [ { "item": "Exact delivery version and supported installation route", "owner": "Delivery contact", "verification": "Matches target; new r232 first-admin C7 remains unresolved" }, { "item": "One permitted operation and acceptance criteria", "owner": "PoC owner and product administrator", "verification": "Written scope and operation permission; no health-only inference" }, { "item": "Client, service, account and endpoint", "owner": "Appliance operator", "verification": "Matching local client/service and supplied socket; no invented startup" }, { "item": "Non-secret input and retention choices", "owner": "Data owner", "verification": "Approved input and private report handling" }, { "item": "AI model, identity, network and cost if needed", "owner": "Cloud/AI owner", "verification": "Supported customer procedure and actual work validation; not proven by local audit" }, { "item": "Report access and human review", "owner": "Service operator and named reviewer", "verification": "Readable authorized artifacts and explicit review responsibility" } ], "routes": [ { "id": "planning", "title": "Prepare and review", "description": "Use the worksheet, recorded example and owner handoff without executing the product.", "limit": "A plan is not installed or authorized product state." }, { "id": "retained-run", "title": "Read the recorded local R234 run", "description": "Follow selected actual fields through one audit Work and JSON/PDF review.", "limit": "Historical local candidate evidence, not a live session or r232/customer/production validation." }, { "id": "conditional-existing-operator", "title": "Reproduce only on an eligible existing installation", "description": "Use the exact command references after its operator verifies matching release, authority and prerequisites.", "limit": "Not an install/bootstrap recipe; new r232 C7 and unresolved readiness stop dependent work." } ], "steps": [ { "id": "plan", "title": "1. Choose one question worth answering", "goal": "Agree what the evaluation will teach you before spending or submitting.", "route": "planning", "inputs": [ "Named PoC owner and reviewer", "Non-confidential sample and intended use" ], "actions": [ "Choose either reading the retained audit example or, if already eligible, reproducing the supported audit operation. CREATE_AUDIT_ARTIFACT creates a structured local audit artifact; it does not audit arbitrary attached documents.", "Write acceptance criteria, budget, permitted actions and stop conditions. Separate a desired AI use case from this local audit example.", "Assign cloud, AI, data, product access and service-operation responsibilities. One person may fill several responsibilities; each requires its own access.", "Use the evaluation workbook to turn each criterion into an observable expectation, a check and an evidence reference. Agree any task-quality, time or cost threshold before execution; there is no default product pass score." ], "expected": [ "A chosen route, exact question, criterion plan, named owners, planned budget and stop conditions. Actual observations remain blank." ], "stop": [ "Unclear authority, cost owner or sensitive input: resolve with the PoC/data owner before operational work." ], "retain": [ "Planning worksheet and unresolved dependencies" ], "source_refs": [ { "file": "customer-poc-guide-en.html", "anchor": "scenario" }, { "file": "customer-poc-guide-en.html", "anchor": "prepare" }, { "file": "headless-operations-guide-en.html", "anchor": "headless-tutorial-scope" } ], "snippets": [] }, { "id": "choose-route", "title": "2. Choose the route your evidence supports", "goal": "Avoid treating a recorded example as a customer installation procedure.", "route": "planning", "inputs": [ "Delivery version and environment, or an explicit unknown" ], "actions": [ "New r232 customer: prepare the plan and request the matching Marketplace/deployment/first-administrator procedures. Stop administrator-dependent use at C7.", "Existing authorized installation: obtain the handoff in step 4 and confirm the operation is supported for its exact release.", "Read the retained local R234 example now even if operational prerequisites are missing. No account, endpoint or provider is needed to read it." ], "expected": [ "A recorded route choice: planning, retained-run reading, or conditional existing-operator reproduction." ], "stop": [ "Do not infer product authority from SSH, Cloud IAM, OS root, purchase or a running VM." ], "retain": [ "Chosen route, release, missing procedure and responsible contact" ], "source_refs": [ { "file": "customer-poc-guide-en.html", "anchor": "admin" }, { "file": "customer-poc-guide-en.html", "anchor": "ready" }, { "file": "headless-operations-guide-en.html", "anchor": "headless-start" } ], "snippets": [] }, { "id": "recorded-run", "title": "3. Read one actual Work before trying your own", "goal": "Recognize the action, outcome and limits of the retained example.", "route": "retained-run", "inputs": [ "Bundled Headless guide and six-step recorded-run reader" ], "actions": [ "Open headless-worked-run-en.html; then read the tutorial sections of the Headless reference. This is selected actual output, not a live terminal.", "Follow the successful wording create audit artifact through submission, list, show, report and file checks. Read the earlier rejected wording only as history; do not execute it as a test.", "Notice the health exit 1/UNKNOWN observations and separately approved admission in that specific lab. That history is not permission to ignore your own missing readiness requirement." ], "expected": [ "The recorded report has execution_count 1, validation_results PASSED, final_result AUTOMATION_COMPLETED_HUMAN_ACCEPTANCE_PENDING and closure.human_acceptance null.", "The service was stopped after collection. Conversational approval did not change the product’s observed AWAITING_HUMAN_ACCEPTANCE state." ], "stop": [ "Do not copy the recorded Work ID, endpoint or digests into a new execution.", "This R234 local record is neither r232 customer proof nor a production AI result." ], "retain": [ "Notes separating observed result, pending human acceptance and applicability to your installation" ], "source_refs": [ { "file": "headless-operations-guide-en.html", "anchor": "headless-tutorial-scope" }, { "file": "headless-operations-guide-en.html", "anchor": "headless-tutorial-report" }, { "file": "headless-operations-guide-en.html", "anchor": "headless-tutorial-recovery" }, { "file": "headless-worked-run-en.html", "anchor": "" } ], "snippets": [] }, { "id": "handoff", "title": "4. Obtain an operating handoff", "goal": "Make an eligible reproduction concrete without inventing setup commands.", "route": "conditional-existing-operator", "inputs": [ "Matching installed client/service release", "Authorized local account and private writable working directory" ], "actions": [ "Ask delivery for the installed packrctl location and exact service release. Ask the service operator for its absolute local socket and running-state confirmation.", "Ask the product administrator to confirm CREATE_AUDIT_ARTIFACT permission; ask the Work owner for one unused approved key and a reviewer.", "Confirm access to returned report files or an approved copy procedure. A local socket is not a remote connection; a desktop terminal does not automatically reach the appliance.", "For a separate AI PoC, obtain supported model/location, identity/access, billing limit and storage/retention procedure. This audit example does not validate those connections or incur demonstrated AI usage.", "List each missing handoff item in the issue sheet with its owner, required evidence and resume condition. Planning and recorded reading can continue independently." ], "expected": [ "Every required handoff item has an owner and a verifiable value for the intended installation." ], "stop": [ "Missing startup/admin/AI/storage procedure: request it; do not create keys, grants, sandbox state or replacement binaries.", "The separately repaired Admin demonstration candidate is not an existing Golden-operational complement or customer bootstrap." ], "retain": [ "Version, target, approved scope and non-secret handoff confirmation; keep private endpoint/account details local" ], "source_refs": [ { "file": "headless-operations-guide-en.html", "anchor": "headless-tutorial-handoff" }, { "file": "customer-poc-guide-en.html", "anchor": "ai" }, { "file": "customer-poc-guide-en.html", "anchor": "storage" }, { "file": "vibepackr-admin-guide-en.html", "anchor": "admin-prerequisites" } ], "snippets": [] }, { "id": "baseline", "title": "5. Query the same service and decide whether to stop", "goal": "Record actual status and component reasons before submission.", "route": "conditional-existing-operator", "inputs": [ "Completed handoff", "Fresh private output directory" ], "actions": [ "In the supplied local client environment, replace both absolute path placeholders, then use the baseline block. Keep the same shell/account/socket for following steps.", "Read status.json and health.json locally. Record both printed status_exit and health_exit values, plus each relevant state/reason. The snippet captures each exit immediately after its command. A zero exit does not grant Work authority.", "If requirements are unknown or non-ready, ask the component owner to resolve applicability before submitting; do not repeat the lab’s exception by assumption." ], "expected": [ "A timestamped baseline with liveness, readiness, authority/runtime observations and exit code." ], "stop": [ "Missing command: delivery/operator verifies installation path. Transport failure: operator checks endpoint/service. Authorization denial: administrator reviews binding.", "Do not turn nonzero health into an automatic restart." ], "retain": [ "Sanitized baseline summary; raw response files remain private" ], "source_refs": [ { "file": "headless-operations-guide-en.html", "anchor": "headless-tutorial-baseline" }, { "file": "headless-operations-guide-en.html", "anchor": "headless-health" }, { "file": "headless-operations-guide-en.html", "anchor": "headless-troubleshoot" } ], "snippets": [ { "id": "poc-baseline", "source_file": "headless-operations-guide-en.html", "source_anchor": "reference-headless-tutorial-baseline-1", "code": "PACKRCTL=\"/ABSOLUTE/SUPPLIED/PATH/packrctl\"\nSOCKET=\"/ABSOLUTE/SUPPLIED/PATH/control-plane.sock\"\n\"$PACKRCTL\" --help\n\"$PACKRCTL\" --socket \"$SOCKET\" status --json > status.json\nSTATUS_EXIT=$?\n\"$PACKRCTL\" --socket \"$SOCKET\" health --json > health.json\nHEALTH_EXIT=$?\nprintf 'status_exit=%s\\nhealth_exit=%s\\n' \"$STATUS_EXIT\" \"$HEALTH_EXIT\"" } ] }, { "id": "submit-once", "title": "6. Submit one explicitly permitted audit operation", "goal": "Create one intentional Work and keep its returned identity.", "route": "conditional-existing-operator", "inputs": [ "All operation-specific prerequisites resolved", "Unused approved key" ], "actions": [ "Replace the key placeholder and keep the supported intent exactly as shown. Execute the submit block only for the separately authorized reproduction; reading this package does not submit anything.", "Open work-run.json locally. Save result.work.work_id with your key and exit code.", "The convenience command prepares and executes and writes records. Do not treat it as a read-only probe or generic AI prompt runner." ], "expected": [ "A response whose Work identity and outcome can be inspected; do not pre-fill success." ], "stop": [ "Timeout, missing ID, DENIED, STOP_WITH_FINDING, FAILED or PARTIAL: preserve the result and reconcile before further action.", "execution_retry_allowed false forbids automatic retry. Re-running the helper is not exact prepared-envelope replay." ], "retain": [ "Original key/request context, time, exit and exact returned Work ID" ], "source_refs": [ { "file": "headless-operations-guide-en.html", "anchor": "headless-tutorial-submit" }, { "file": "headless-operations-guide-en.html", "anchor": "headless-run" }, { "file": "headless-operations-guide-en.html", "anchor": "headless-result" } ], "snippets": [ { "id": "poc-submit-once", "source_file": "headless-operations-guide-en.html", "source_anchor": "reference-headless-tutorial-submit-1", "code": "WORK_KEY=\"REPLACE_WITH_ONE_UNUSED_APPROVED_KEY\"\n\"$PACKRCTL\" --socket \"$SOCKET\" work run CREATE_AUDIT_ARTIFACT \"create audit artifact\" \"$WORK_KEY\" --json > work-run.json\nRUN_EXIT=$?\nprintf '%s\\n' \"$RUN_EXIT\"" } ] }, { "id": "same-work", "title": "7. Reconcile and inspect that same Work", "goal": "Prevent a second execution from being mistaken for recovery.", "route": "conditional-existing-operator", "inputs": [ "Exact returned result.work.work_id" ], "actions": [ "Paste your own Work ID in the query block; keep the original account and socket.", "Compare works[].work_id in list with work.work_id, reports[].work_id and selected_report.canonical_report.work_id in show.", "If absent from the last 10, show the saved ID directly or use the documented list limit up to 100. An empty scoped list is not proof of no Work anywhere.", "If submission returned no ID, preserve request context and ask support to reconcile the original installation/principal before another submission." ], "expected": [ "All inspected records refer to one saved Work; ambiguity is recorded rather than replaced by a new Work." ], "stop": [ "Identity mismatch, denied show or missing selected report: stop completion claims. Do not switch accounts to bypass a denial." ], "retain": [ "Work ID, chosen report revision and sanitized reconciliation result" ], "source_refs": [ { "file": "headless-operations-guide-en.html", "anchor": "headless-tutorial-reconcile" }, { "file": "headless-operations-guide-en.html", "anchor": "headless-work" } ], "snippets": [ { "id": "poc-same-work", "source_file": "headless-operations-guide-en.html", "source_anchor": "reference-headless-tutorial-reconcile-1", "code": "WORK_ID=\"PASTE_EXACT_result.work.work_id_FROM_work-run.json\"\n\"$PACKRCTL\" --socket \"$SOCKET\" work list --limit 10 --json > work-list.json\n\"$PACKRCTL\" --socket \"$SOCKET\" work show \"$WORK_ID\" --json > work-show.json" } ] }, { "id": "outcome", "title": "8. Read validation, receipt and closure together", "goal": "Separate automated completion from human acceptance.", "route": "conditional-existing-operator", "inputs": [ "Same-Work show response" ], "actions": [ "Read selected_report.canonical_report: work_id, execution_count, final_result, validation_results, receipt and closure. Retain actual values, not the example’s expected values.", "Read closure.disposition, closure.human_acceptance_required and closure.human_acceptance. Read replayed and execution_retry_allowed in the returned result.", "PASSED is validation, not human acceptance. A replayed result is not a new execution. Missing receipt/closure needs support reconciliation.", "Use the criterion observation sheet to distinguish the expected value from the literal value observed. Mark an unperformed check as not run; give a reason for non-applicability. These are human worksheet labels, not product status." ], "expected": [ "An accurate outcome statement; the retained example is automation completed with human acceptance pending." ], "stop": [ "Do not call FAILED/PARTIAL unchanged state or call a process exit product success." ], "retain": [ "Sanitized outcome and pending reviewer decision" ], "source_refs": [ { "file": "headless-operations-guide-en.html", "anchor": "headless-tutorial-report" }, { "file": "headless-operations-guide-en.html", "anchor": "headless-result" } ], "snippets": [] }, { "id": "reports", "title": "9. Obtain and verify the JSON and PDF", "goal": "Review readable artifacts for the exact Work and revision.", "route": "conditional-existing-operator", "inputs": [ "selected_report.json_path and selected_report.pdf_path", "Authorized local viewer or operator-supplied approved copies" ], "actions": [ "Use your returned paths, never a guessed report directory. Confirm files exist, are readable and match the selected Work/revision.", "On macOS the shared checksum block uses shasum; otherwise use the file verifier supplied for your platform. Compare JSON bytes to selected_report.projection.json_file_sha256 and PDF bytes to selected_report.projection.pdf_sha256, removing its sha256: prefix for comparison.", "Keep report_sha256 distinct from file hashes. It is the report digest, not the checksum of the saved JSON or PDF.", "Open the PDF in an authorized viewer and compare Work, execution count and validation with JSON. A server path is not proof of delivery to your computer." ], "expected": [ "Matched, readable JSON/PDF for one report revision. No separate underlying output artifact is promised by this step." ], "stop": [ "Missing/unreadable file or digest mismatch: retain the reference and ask the service operator/support; do not silently regenerate or substitute another report." ], "retain": [ "Report revision, comparison result and minimal approved references; raw reports stay private" ], "source_refs": [ { "file": "headless-operations-guide-en.html", "anchor": "headless-tutorial-files" }, { "file": "headless-operations-guide-en.html", "anchor": "headless-result" } ], "snippets": [ { "id": "poc-file-hashes-macos", "source_file": "headless-operations-guide-en.html", "source_anchor": "reference-headless-tutorial-files-2", "code": "REPORT_JSON=\"PASTE_EXACT_selected_report.json_path\"\nREPORT_PDF=\"PASTE_EXACT_selected_report.pdf_path\"\nshasum -a 256 \"$REPORT_JSON\" \"$REPORT_PDF\"" } ] }, { "id": "human-review", "title": "10. Review usefulness and record the human decision", "goal": "Answer the original PoC question without changing product acceptance by implication.", "route": "planning", "inputs": [ "Plan criteria", "Retained-run notes or actual eligible reproduction results" ], "actions": [ "The named reviewer compares the result with the agreed goal, permitted input, cost and retention boundaries. For the audit example, judge the structured artifact/report trace, not arbitrary content quality.", "Record the human’s review separately from the product’s latest closure state. This guide supplies no product acceptance command.", "If no provider was called or billing evidence was not collected, record not measured/not applicable with the reason; do not invent a cost or runtime result.", "Complete the criterion-by-criterion evaluation and the final human review: what was learned, what remains blocked, which owner acts next and what evidence would change the decision. Do not reduce unresolved required criteria to an average score." ], "expected": [ "A signed-off or unresolved human evaluation record and the separately observed product acceptance state." ], "stop": [ "A conversation approval or completed checklist must not overwrite AWAITING_HUMAN_ACCEPTANCE in reporting." ], "retain": [ "Reviewer, date, criteria result, open issues and product state", "Completed criterion observations and final human review, or an explicitly unresolved disposition" ], "source_refs": [ { "file": "customer-poc-guide-en.html", "anchor": "first-work" }, { "file": "headless-operations-guide-en.html", "anchor": "headless-tutorial-scope" }, { "file": "headless-operations-guide-en.html", "anchor": "headless-tutorial-report" } ], "snippets": [] }, { "id": "cleanup", "title": "11. Close the exercise and hand off remaining work", "goal": "Preserve required results and leave resources in an agreed state.", "route": "planning", "inputs": [ "Exact resources used", "Data owner retention choices", "Operator’s supported stop/retirement procedure" ], "actions": [ "Reading-only route: retain your worksheet; there is no product process to stop.", "Operational route: ask the service operator to stop only an exercise-owned service when authorized by its supplied procedure. A closed GUI does not prove service shutdown.", "Have cloud/data owners review VM, disks, objects, backups and continuing charges separately. This guide provides no deletion or credential-revocation command.", "Send support the version, failed stage, expected/observed result, time, literal sanitized reason and minimal Work/report reference. Request a private channel before extra identifiers.", "Complete one closeout row for each used resource. Record before/after state, retained data, owner, retention review date, remaining charges and evidence. Compare actual cost over a named billing period with the agreed budget; unknown or delayed billing remains unmeasured." ], "expected": [ "A completed closeout or an explicitly open item for each resource and cost line, plus a named owner and resume condition for every unresolved issue." ], "stop": [ "Unknown ownership or retention effect: stop deletion/restarts and ask the responsible owner. Never reuse test teardown as customer cleanup proof." ], "retain": [ "Cleanup confirmations, retained-report location kept private, outstanding owner/action" ], "source_refs": [ { "file": "customer-poc-guide-en.html", "anchor": "restart" }, { "file": "customer-poc-guide-en.html", "anchor": "retire" }, { "file": "customer-poc-guide-en.html", "anchor": "support" }, { "file": "headless-operations-guide-en.html", "anchor": "headless-tutorial-recovery" } ], "snippets": [] } ], "planning_example": { "status": "ILLUSTRATIVE", "title": "Filled planning example—not executed results", "fields": { "goal": "Understand whether an approved audit operation can be traced from one Work to a readable report.", "route": "Read retained run first; consider eligible operator reproduction only after handoff.", "input": "Supported create audit artifact intent; no confidential document attachments.", "acceptance_criteria": "Identify one Work consistently; understand validation, closure and report-file hash checks; record reviewer disposition separately.", "cost_plan": "No provider action in the reading exercise; operational cost limit must be assigned by the owner before execution.", "owners": "PoC lead, service operator, product administrator and reviewer—assign actual names locally.", "retention": "Keep raw responses and reports private; share approved selected fields only.", "unresolved": "Matching installation and authority have not been claimed for this example." } }, "faq": [ { "question": "Can I start if health exits 1 as in the recorded run?", "answer": "No general permission follows from that history. The lab had separate approval and normal admission evaluated that operation. Resolve your own required readiness and authority before submission." }, { "question": "Is this an executable Pack I can import into Packtory?", "answer": "No. This is a documentation package. It is not a registered payload, installed Pack, authority grant or product execution." }, { "question": "Can the audit command analyze my uploaded business document?", "answer": "This registered operation creates a structured local audit artifact. It does not inspect arbitrary attached content." }, { "question": "What if the command times out?", "answer": "Keep the key/request context and reconcile the original Work under the same installation/account. Do not submit a replacement or add an automatic retry." }, { "question": "Does the repaired Admin example unblock Golden r232?", "answer": "No. It used a separately repaired task-local candidate and disposable target. It is not a Golden change, customer bootstrap or inherited production capability." }, { "question": "What do I send support?", "answer": "Version, stage, expected and observed behavior, time and sanitized reason; minimal Work/report reference when appropriate. No credentials, raw reports, private paths, full logs or customer payloads." } ], "limits": [ "Documentation review edition; blank worksheets and the illustrative reading example do not execute or register a Pack.", "Golden r232 remains immutable. New-customer C7 and full customer AI/storage/lifecycle procedures are not completed here.", "Local R234 recorded Work is bounded evidence; this package creates no new runtime or production evidence.", "Repaired Admin candidate complements the reference material, not the operational capabilities of existing Golden installations.", "Commands follow the active Headless reference. R1 adds immediate status exit capture to the baseline snippet; retained historical outputs and the original R0 archive are unchanged. No historical rejected input is offered as a runnable test.", "Raw JSON/PDF, execution responses, credentials and internal support exports are not public attachments.", "Human review and product acceptance are separate; unknown values remain unknown." ], "worksheet_fields": [ "Route chosen", "PoC question and acceptance criteria", "Exact release / target confirmation", "PoC owner / operator / administrator / reviewer", "Permitted operation / non-secret input", "AI requirement, model/location/identity owner if applicable", "Cost limit and billing owner", "Data retention and cleanup owner", "Missing prerequisites / responsible person / next action", "Observation time / command reference / exit code", "Health component states and literal reasons", "Approved request key (private local record)", "Returned Work ID / installation-principal scope confirmation", "Work/report ID correspondence and selected report revision", "Execution count / final_result / validation_results", "Receipt / closure disposition / human_acceptance_required / human_acceptance", "execution_retry_allowed / replayed", "JSON/PDF readable / file-hash comparison result", "Report digest (distinct from file SHA-256)", "Actual runtime/provider/cost observation or explicitly not measured", "Human reviewer / date / criteria result", "Product acceptance state separately observed", "Authorized cleanup / retained resources / remaining costs", "Unresolved issue / sanitized support handoff", "Criterion ID / applicability basis / expected value / observed value / evidence / reviewer disposition", "Cost category / budget / observed amount / currency / billing period / evidence / remaining charges", "Resource owner / before-after state / retained data / retention review date / closeout evidence", "Issue owner / requested information / next action / exact resume condition / open status" ], "workbook_url": "/guides/poc/workbook.html", "completed_example_url": "/guides/poc/example.html" }