ask-just 0.1.0__tar.gz

ask_just-0.1.0/PKG-INFO

@@ -0,0 +1,777 @@
+Metadata-Version: 2.4
+Name: ask-just
+Version: 0.1.0
+Summary: Thin CLI for the hosted Ask Just source plane
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Ask Just
+
+Ask Just is the first source-backed company model of Just.
+
+The `ask-just` CLI and hosted API remain the stable technical surface for
+compatibility. Ask Just is the model identity above that source plane: verified
+source lanes, provenance rows, source-routing rules, correction memory, Deep
+Research bundles, and governed action boundaries.
+
+The goal is simple: a teammate should be able to ask Just what it knows, inspect
+the evidence, challenge the answer, and improve the memory as new artifacts
+appear.
+
+## Teammate Setup
+
+Install Ask Just for a teammate with one command:
+
+```bash
+uvx ask-just setup --code JST-MZ6X-F56K
+```
+
+The code is stable until Josh or an admin rotates it. This command installs or
+refreshes the persistent CLI, exchanges the setup code, configures Codex and
+Claude Code, runs doctor, runs the canonical verification query, and reports
+the source id.
+
+Under the hood, Ask Just does not ask a live app, SharePoint folder, exported
+row set, or loose pile of files every time. It follows the source contract:
+
+```text
+map the source -> access it -> enumerate it where needed -> parse it into atomic units or live-query proof records -> verify receipts -> make it queryable
+```
+
+Once a source passes that gate, normal Ask Just answers come through the hosted
+API backed by the GCP VM source index with provenance. That is what makes
+answers fast, repeatable, and inspectable without turning local rebuild
+artifacts into answer fallbacks.
+
+Read [SPEC.md](SPEC.md) for the deeper product contract and future direction.
+Read [docs/ask-just-model-card.md](docs/ask-just-model-card.md) for the model card
+and [docs/ask-just-release-notes.md](docs/ask-just-release-notes.md) for release
+history.
+Read [docs/ask-monarch-flow-map.md](docs/ask-monarch-flow-map.md) for the
+piece-by-piece mapping from Monarch-1 to Ask Just.
+Read [docs/source-receipts/completion-audit.md](docs/source-receipts/completion-audit.md)
+for the phase audit behind the current source-plane claim.
+Read [docs/full-source-completion-frontier.md](docs/full-source-completion-frontier.md)
+for what is active now and what is explicitly not yet claimed.
+
+## Architecture
+
+Ask Just has two flows: source onboarding builds the verified SQLite/FTS index
+on the VM, and the `ask-just` CLI calls the hosted API to ask that index for
+evidence.
+
+![Ask Just architecture](docs/ask-just-architecture.png)
+
+## Source Lane Change Rule
+
+Every new answerable source lane must update the product contract and the
+explainable architecture in the same change. A lane is not done if it only
+appears in parser code or source maps.
+
+For each new source id, update:
+
+- `config/all-source-ids.json`, `config/queryable-source-ids.json`, and
+  `config/fresh-source-map.yaml`
+- parser code, receipts, hosted VM SQLite verification, and freshness proof
+- `README.md`, `SPEC.md`, and `ARCHITECTURE.md`
+- `docs/ask-just-architecture.svg` and the rendered
+  `docs/ask-just-architecture.png`
+
+## Visual Explainers
+
+Ask Just's architecture explainer is a repo-owned static SVG rendered to PNG.
+The SVG is the editable source; the PNG is the README-facing asset.
+
+```bash
+sips -s format png docs/ask-just-architecture.svg --out docs/ask-just-architecture.png
+```
+
+Use these visuals to explain product boundaries like:
+
+```text
+ask-just CLI -> HTTPS JSON API -> VM SQLite -> sourced answer
+```
+
+If the API is unavailable, the correct behavior is to fix the API path, not to
+answer through SSH or direct SQLite.
+
+## Current State
+
+## Ask Just Actions
+
+Ask Just is also the home for company actions. Actions are not separate agents,
+managed-agent runtimes, bots, or sidecar operators. Ask Just is the company
+brain, hands, and arms: it reads source-grade inputs, drafts an operational
+decision, asks for human approval where the action is risky or external, executes
+through owned tools, and writes receipts back into the source plane.
+
+Order allocation is the first declared action candidate. Its source boundary is
+`operations_order_allocation`, which is declared but not queryable until the
+daily inventory, demand, routing, inbound, human-review, and NetSuite commit
+evidence is mapped, parsed, receipted, and exposed through the hosted API.
+
+The v0 command surface is deliberately inside Ask Just:
+
+```bash
+ask-just actions order-allocation prepare --run-date 2026-05-06
+ask-just actions order-allocation rehearse --run-date 2026-05-06
+ask-just actions order-allocation process-approved --run-date 2026-05-06
+ask-just actions order-allocation status RUN_ID
+ask-just actions order-allocation receipts RUN_ID
+```
+
+Until the source lane is fresh and atomically queryable, these commands must
+fail closed with freshness and repair instructions rather than drafting from
+raw mail, Evista, NetSuite, SharePoint, local files, or chat context.
+`rehearse` is the safe practice surface: it uses the same source freshness gate
+as a real allocation pass, but returns a no-commit practice packet with
+NetSuite writes, approved-artifact processing, and external sends disabled.
+
+Prepare-time source proof records land here:
+
+```text
+source-material/operations_order_allocation/source-family-proofs/*.json
+```
+
+The builder materializes them as
+`operations_order_allocation_source_family_proofs` rows. The first supported
+families are `inventory_vernon`, `inventory_bethlehem`,
+`inventory_vertical_evista`, `netsuite_open_orders`, `routing_rules`, and
+`operations_inbound_log`.
+
+Capture helper:
+
+```bash
+python3 scripts/capture_order_allocation_source_proofs.py mailbox-inventory --family-id inventory_vernon --freshness-date 2026-05-06
+python3 scripts/capture_order_allocation_source_proofs.py mailbox-inventory --family-id inventory_bethlehem --freshness-date 2026-05-06
+python3 scripts/capture_order_allocation_source_proofs.py evista-inventory --freshness-date 2026-05-06
+python3 scripts/capture_order_allocation_source_proofs.py sharepoint-file --family-id routing_rules --freshness-date 2026-05-06 --drive-id DRIVE_ID --item-id ITEM_ID --source-uri "sharepoint:/sites/operations/Shared Documents/Automation/OOR Automation - Customer and Carrier tables.xlsx"
+python3 scripts/capture_order_allocation_source_proofs.py sharepoint-file --family-id operations_inbound_log --freshness-date 2026-05-06 --drive-id DRIVE_ID --item-id ITEM_ID --source-uri "sharepoint:/sites/operations/Shared Documents/Inbound Log/Inbound Log 2026.xlsx"
+python3 scripts/capture_order_allocation_source_proofs.py netsuite-open-orders --freshness-date 2026-05-06 --run-date 2026-05-06
+python3 scripts/build_fresh_source_database.py --source-id operations_order_allocation
+```
+
+`evista-inventory` requires `VERTICAL_USER`/`VERTICAL_PASS` or
+`EVISTA_USERNAME`/`EVISTA_PASSWORD` in the Ask Just VM refresh environment.
+`mailbox-inventory` inherits the previous order-allocation Microsoft Graph
+shape (`GRAPH_TENANT_ID`, `GRAPH_CLIENT_ID`, `GRAPH_CLIENT_SECRET`) as well as
+the Ask Just `MS_*` aliases. Vernon defaults to
+`noreply@onelineage.com` plus `Inventory Stock Summary Report`; Bethlehem
+defaults to `no-reply-powerbi@microsoft.com` plus
+`Eat Just Fulfillment On Hand Report`. For local operator runs, pass
+`--env-file /path/to/order-allocation.env` rather than copying secrets into the
+repo.
+
+Run NetSuite capture in the Ask Just runtime/VM credential context. Ask Just has
+NetSuite read/write access; a laptop shell missing `NETSUITE_*` is only a local
+execution-context issue.
+
+## Current State
+
+Ask Just's answerable data lives behind the hosted API in the active GCP VM
+SQLite source index. Exact answers must come from rows returned by `ask-just`;
+repo docs, maps, receipts, local rebuild artifacts, and tests describe or
+verify that index, but they are not answer data.
+
+The active source inventory is generated, not hand-maintained:
+
+- Declared source ids: `config/all-source-ids.json`
+- Ask-surface source ids: `config/queryable-source-ids.json`
+- Strict lane table: `docs/strict-source-completion-table.md`
+- Current external blockers: `docs/source-required-inputs.md`
+- Completion audit: `docs/source-goal-completion-audit.md`
+
+As of the 2026-05-10 DOT Foodservice weekly sales lane addition, Ask Just declares 62 source lanes
+in `config/all-source-ids.json`; 60 are intended for the Ask surface in
+`config/queryable-source-ids.json`. `tofutown_qvd_last_90_days` and
+`operations_order_allocation` are deliberately declared but not queryable.
+`tofutown_qvd_last_90_days` waits on current QVD file access and row parsing
+inside the rolling 90-day window. `operations_order_allocation` waits on source
+grade daily inventory, demand, routing, inbound, human-review, and commit
+evidence. The Qlik app-model snapshot lane and Dirk stock/service-level workbook
+lane are scoped to last-90-day evidence. The four TofuTown / Just Europe finance
+workbook lanes and TofuTown people-operations lanes remain separate source
+boundaries. `operations_logistics_otif_2024v2`
+covers the exact Operations / ALLOCATION workbook and its revised OT/IF/OTIF
+formula cells and threaded comments; Scorecard remains canonical for plain KPI
+values unless the user asks for workbook calculation mechanics.
+
+Every source lane must carry a freshness contract: source of truth, declared
+boundary, query plane, freshness mechanism/cadence, last checked/refreshed
+proof, stale behavior, and whether it is current-truth or snapshot-only. SPINS
+lanes are delivered reporting snapshots keyed to the workbook data ending date.
+Every non-SPINS lane must refresh daily at midnight America/Los_Angeles through
+the VM timer or an equivalent source-specific delta proof before current-truth
+answers.
+
+## Deep Research Max Contract
+
+Deep Research Max must cover every shared verified Ask Just source lane before
+launch. The lane list is generated from the hosted `ask-just sources` surface
+and cross-checked against `config/queryable-source-ids.json`, not from a
+prompt-specific "relevant lanes" list or any manual checklist.
+
+The launch preflight must stop before launching Gemini if any shared verified
+source lane is missing from the hosted Ask Just `/sources` surface, lacks the
+required `mapped`, `accessible`, and `atomically_queryable` gates, has no
+freshness contract, has no hosted source-file receipt rows, or has no hosted
+atomic rows. The evidence bundle must include `source_lanes_covered` with the
+full generated lane list. Relevance affects row selection and ranking inside
+each lane; it does not affect lane coverage.
+
+Personal/private overlays stay excluded from Deep Research Max unless they have
+been promoted into the shared verified source lane inventory. A user's personal
+mailbox overlay, for example, is not part of the team-visible source plane and
+must not be pulled into the bundle.
+
+Dry bundle-only proof:
+
+```bash
+python3 scripts/deep_research_just.py --bundle-only --row-limit 0
+```
+
+| Source id | Layer | Query plane | Freshness contract | Ask surface |
+| --- | --- | --- | --- | --- |
+| `rd_powerjacks_formulations` | r_and_d | `sharepoint_workbook_snapshot` | `daily_midnight_snapshot_check` | yes |
+| `rd_formulations_vault_production_formulas` | r_and_d_production_formulas | `sharepoint_document_library` | `daily_midnight_sharepoint_graph_recursive_refresh` | yes |
+| `spins_plant_based_meat_powertabs` | sales_and_retail_velocity | `local_xlsb_workbook_snapshot` | `scheduled_snapshot` | yes |
+| `spins_breakfast_powertabs` | sales_and_retail_velocity | `local_xlsb_workbook_snapshot` | `scheduled_snapshot` | yes |
+| `spins_condiments_powertabs` | sales_and_retail_velocity | `local_xlsb_workbook_snapshot` | `scheduled_snapshot` | yes |
+| `spins_protein_powder_powertabs` | sales_and_retail_velocity | `local_xlsb_workbook_snapshot` | `scheduled_snapshot` | yes |
+| `operations_production_plan_latest` | operations_planning | `sharepoint_xlsx_workbook_snapshot` | `daily_midnight_graph_delta_snapshot` | yes |
+| `ejp_protein_release_tracker` | quality_and_batch_release | `sharepoint_xlsx_workbook_snapshot` | `daily_midnight_graph_delta_snapshot` | yes |
+| `operations_inbound_log` | operations_logistics | `sharepoint_xlsx_workbook_snapshot` | `daily_midnight_graph_delta_snapshot` | yes |
+| `quality_vault_finalized_sops` | quality_and_batch_release | `sharepoint_document_library` | `daily_midnight_sharepoint_graph_recursive_refresh` | yes |
+| `rd_processdev_egb_sops` | r_and_d_quality_sops | `sharepoint_document_library` | `daily_midnight_sharepoint_graph_recursive_refresh` | yes |
+| `rd_processdev_project_onestream` | r_and_d_processdev_projects | `sharepoint_document_library` | `daily_midnight_sharepoint_graph_recursive_refresh` | yes |
+| `operations_order_allocation` | operations_order_allocation | `declared_multi_system_order_allocation_boundary` | `daily_midnight_mailbox_evista_netsuite_sharepoint_refresh` | declared gap; not queryable |
+| `operations_logistics_otif_2024v2` | operations_logistics | `sharepoint_xlsx_workbook_snapshot` | `daily_midnight_graph_delta_snapshot` | yes |
+| `tofu_town_production_planning` | tofu_town_operations | `local_xlsx_workbook_set_snapshot` | `daily_midnight_delivered_snapshot_check` | yes |
+| `tofutown_qlik_cloud_app_models` | tofutown_operations_data_lineage | `qlik_cloud_app_query_export_snapshot` | `weekly_saturday_midnight_current_qlik_api_snapshot_last_90_days_only` | yes |
+| `tofutown_qvd_last_90_days` | tofutown_operations_qvd_facts | `qlik_qvd_file_contents` | `weekly_saturday_midnight_current_qvd_file_pull_last_90_days_only` | declared gap; not queryable |
+| `tofutown_dirk_stock_level_workbook` | tofutown_operations_stock_service_level | `sharepoint_xlsx_workbook_snapshot_last_90_days` | `weekly_saturday_midnight_sharepoint_workbook_snapshot_last_90_days_only` | yes |
+| `weekly_tofutown_just_europe_sales` | weekly_tofutown_just_europe_sales | `local_xlsb_workbook_snapshot` | `weekly_delivered_navision_sales_export_snapshot` | declared only; source-surface gap |
+| `tofutown_standard_cost_gross_margin_by_sku_2026_05` | tofutown_just_europe_finance | `sharepoint_xlsx_workbook_snapshot` | `daily_midnight_delivered_snapshot_check_until_tofutown_graph_refresh` | yes |
+| `tofutown_bom_tt_skus` | tofutown_just_europe_finance | `sharepoint_xlsx_workbook_snapshot` | `daily_midnight_delivered_snapshot_check_until_tofutown_graph_refresh` | yes |
+| `tofutown_financial_tracking_week_18` | tofutown_just_europe_finance | `sharepoint_xlsx_workbook_snapshot` | `daily_midnight_delivered_snapshot_check_until_tofutown_graph_refresh` | yes |
+| `tofutown_preliminary_pl_march_2026` | tofutown_just_europe_finance | `sharepoint_xlsx_workbook_snapshot` | `daily_midnight_delivered_snapshot_check_until_tofutown_graph_refresh` | yes |
+| `just_us_canada_p_and_l_boms` | just_us_canada_finance_bom | `sharepoint_document_library` | `daily_midnight_sharepoint_graph_recursive_refresh` | yes |
+| `qualification_fold_sensory` | r_and_d_quality_sensory | `sharepoint_xlsx_workbook_snapshot` | `daily_midnight_graph_delta_snapshot` | yes |
+| `qualification_meat_sensory` | r_and_d_quality_sensory | `sharepoint_xlsx_workbook_snapshot` | `daily_midnight_graph_delta_snapshot` | yes |
+| `qualification_v5_sensory_analytics` | r_and_d_quality_sensory | `sharepoint_xlsx_workbook_snapshot` | `daily_midnight_graph_delta_snapshot` | yes |
+| `rd_in_market_testing` | r_and_d_quality_sensory | `sharepoint_xlsx_workbook_snapshot` | `daily_midnight_graph_delta_snapshot` | yes |
+| `rd_liquid_egg_v6` | r_and_d_formulation | `sharepoint_xlsx_workbook_snapshot` | `daily_midnight_graph_delta_snapshot` | yes |
+| `reefer_meat_shelf_life_tests` | r_and_d_quality_shelf_life | `sharepoint_xlsx_workbook_snapshot` | `daily_midnight_graph_delta_snapshot` | yes |
+| `target_tracker` | sales_planning_and_retail_performance | `sharepoint_xlsx_workbook_snapshot` | `daily_midnight_graph_delta_snapshot` | yes |
+| `finance_cash_flow_forecast_2026` | finance_accounts_payable_cash_flow | `sharepoint_xlsx_workbook_snapshot` | `daily_midnight_graph_delta_snapshot` | yes |
+| `operations_dashboard_2025` | operations_dashboard | `sharepoint_xlsx_workbook_snapshot` | `daily_midnight_graph_delta_snapshot` | yes |
+| `appleton_jpc_factory_dashboard` | appleton_factory_operations | `external_http_jpc_factory_api_snapshot` | `daily_midnight_http_api_snapshot` | yes |
+| `whole_foods_canada_just_egg_rl_upsw` | sales_and_retail_velocity | `sharepoint_xlsx_workbook_snapshot` | `daily_midnight_graph_delta_snapshot` | yes |
+| `whole_foods_us_who_cube_2026_04_19` | sales_and_retail_velocity | `sharepoint_xlsx_workbook_snapshot` | `daily_midnight_graph_delta_snapshot` | yes |
+| `dot_foodservice_weekly_sales` | foodservice_sales | `local_xlsx_workbook_snapshot` | `weekly_delivered_dot_foodservice_sales_report_snapshot` | yes |
+| `satellite_cpg_eat_just_brochure` | brand_sales_materials | `external_web_app_brochure_snapshot` | `daily_midnight_http_api_snapshot` | yes |
+| `just_phase_3b_proposal` | strategic_project_proposals | `local_pdf_document_snapshot` | `delivered_pdf_snapshot` | yes |
+| `block_from_hierarchy_to_intelligence` | operating_model_reference | `external_web_html_snapshot` | `daily_midnight_http_delta` | yes |
+| `just_public_website_homepage` | public_website_and_brand | `external_web_html_snapshot` | `daily_midnight_http_delta` | yes |
+| `asana_work_management` | work_management | `external_asana_workspace_project_snapshot` | `daily_midnight_api_delta` | yes |
+| `replace_enter_repo_github` | formulation_nutrition_and_labels | `github_repo_snapshot_with_live_app_api_and_local_feed_artifacts` | `daily_midnight_git_delta` | yes |
+| `brand_logo_eat_just_svg` | brand_assets | `local_brand_asset_snapshot` | `daily_midnight_delta_or_equivalent_origin_pending` | yes |
+| `brand_font_neue_haas_grotesk_display_round_zip` | brand_assets | `local_brand_asset_zip_snapshot` | `daily_midnight_delta_or_equivalent_origin_pending` | yes |
+| `hr_just_food_company_headcount` | people_operations | `local_xlsx_workbook_snapshot` | `daily_midnight_delivered_snapshot_check` | yes |
+| `tofutown_employee_list_2026` | people_operations | `sharepoint_xlsx_workbook_snapshot` | `daily_midnight_sharepoint_workbook_snapshot` | yes |
+| `wecare_mailbox_last_30_days` | customer_experience | `live_microsoft_graph_mailbox` | `daily_midnight_graph_delta_equivalent_rolling_30_days` | yes |
+| `just_meat_production_library` | just_meat_production | `sharepoint_document_library` | `daily_midnight_graph_delta_after_recursive_enumeration` | yes |
+| `rd_process_sciences_lab_research` | r_and_d_process_sciences | `sharepoint_document_library` | `daily_midnight_graph_delta_after_recursive_enumeration` | yes |
+| `rd_process_sciences_yield_improvement` | r_and_d_process_sciences | `sharepoint_document_library` | `daily_midnight_graph_delta_after_recursive_enumeration` | yes |
+| `scorecard_monthly_data` | company_kpis | `live_scorecard_api` | `daily_midnight_current_truth_snapshot` | yes |
+| `scorecard_ops_metrics` | operations_kpis | `live_scorecard_api` | `daily_midnight_current_truth_snapshot` | yes |
+| `batch_release_app` | quality_and_batch_release | `live_batch_release_app_state` | `daily_midnight_current_truth_snapshot` | yes |
+| `netsuite_account_catalog` | finance_and_operations | `live_netsuite_account_catalog_audit` | `daily_midnight_current_truth_audit_snapshot` | yes |
+| `netsuite_items` | finance_and_operations | `live_netsuite_suiteql` | `daily_midnight_current_truth_snapshot` | yes |
+| `netsuite_pnl_monthly` | finance_and_operations | `live_netsuite_suiteql` | `daily_midnight_current_truth_snapshot` | yes |
+| `netsuite_ar_open_invoices` | finance_and_operations | `live_netsuite_suiteql` | `daily_midnight_current_truth_snapshot` | yes |
+| `netsuite_ap_open_bills` | finance_and_operations | `live_netsuite_suiteql` | `daily_midnight_current_truth_snapshot` | yes |
+| `netsuite_inventory_snapshot` | finance_and_operations | `live_netsuite_suiteql` | `daily_midnight_current_truth_snapshot` | yes |
+| `netsuite_revenue_by_sku_ytd` | finance_and_sales | `live_netsuite_suiteql` | `daily_midnight_current_truth_snapshot` | yes |
+| `netsuite_revenue_by_customer_sku_channel_ytd` | finance_and_sales | `live_netsuite_suiteql` | `daily_midnight_current_truth_snapshot` | yes |
+
+The Quality/R&D SharePoint document-library lanes are fully source for their
+declared folder boundaries. As of the 2026-05-09 hosted Graph refresh, Quality
+Vault finalized SOPs has 9 folders, 65 files, and 886 atomic rows; R&D
+ProcessDev EGB SOPs has 1 folder, 11 files, and 72 atomic rows. As of the
+2026-05-10 hosted Graph refresh, R&D ProcessDev Project OneStream has 67
+folders, 92 files, and 13,936 atomic rows.
+
+The JUST Phase 3b proposal lane is fully source for the delivered PDF snapshot
+as of the 2026-05-09 hosted parse: 1 source file, 7 PDF text chunks, and 8
+atomic rows. It is proposal evidence only, not approval or current operational
+truth by itself.
+
+The R&D Formulations Vault production-formula lane is canonical for
+production-related formula questions inside the Formulations-Vault SharePoint
+library. As of the 2026-05-10 hosted Graph refresh, it has 109 folders, 166
+files, and 12,331 atomic rows.
+
+Current Braintrust receipt:
+
+- Project: `Andes / ask-just`
+- Project id: `2a580ddb-dbad-4acd-a8b7-eacc2ab91123`
+- Query responses include `trace_id`, `trace_span_id`, `trace_project`, `trace_project_id`, and `trace_url` when `BRAINTRUST_API_KEY` is configured and callers request trace metadata.
+- Query traces include spans for `trace.user_question`, `trace.tool_call.1.ask_just_source_query`, `trace.selected_evidence`, `trace.source_receipts`, and `trace.final_answer`.
+
+The active SQLite default is
+`artifacts/ask-just-fresh-source-plane/source_index.sqlite`.
+
+## How To Ask
+
+In Codex, use the repo-owned skill:
+
+```text
+what was February revenue? [$askjust](/Users/josh/.codex/skills/askjust/SKILL.md)
+```
+
+The user should not need to know which source, database, table, source id, or
+CLI flag contains the answer. `$askjust` means: ask Just's verified source
+plane, choose the right source lane, answer with evidence, and say clearly when
+the local memory does not yet contain enough evidence.
+
+For direct shell use, the `ask-just` CLI calls the hosted Ask Just service.
+
+Install or refresh the CLI from the hosted Ask Just service:
+
+```bash
+bash -c 'curl -fsSL https://ask-just.35.222.146.245.sslip.io/install.sh | bash'
+```
+
+If an admin needs to create a one-time setup code for a teammate:
+
+```bash
+ask-just onboarding-code create --label "Pri setup" --ttl-hours 24
+```
+
+For the employee parity experience, reset the previous Ask Just install, run
+quietly, exchange the one-time setup code for the real token, and let the
+installer run `ask-just doctor`:
+
+```bash
+ASK_JUST_SETUP_CODE='<paste-setup-code-here>' ASK_JUST_RESET=1 ASK_JUST_QUIET=1 bash -c 'curl -fsSL https://ask-just.35.222.146.245.sslip.io/install.sh | bash'
+```
+
+The hosted installer downloads the CLI to `~/.local/bin/ask-just`, refreshes
+the Ask Just Codex skills under `~/.codex/skills/` (`askjust`, `just-source`,
+`correction`, and `braintrust`), configures the token from
+`ASK_JUST_SETUP_CODE` or `ASK_JUST_TOKEN`, enables those skills in the global
+Codex skill config so new threads in any project can see them, runs
+`ask-just doctor`, and writes a managed global `~/.codex/AGENTS.md` rule so
+plain Just questions route through Ask Just instead of web search unless the
+user explicitly asks for web/public lookup. It keeps GitHub out of the normal
+employee setup path.
+`ASK_JUST_RESET=1` removes only the previous Ask Just CLI, local Ask Just
+config, and these four Ask Just skills before reinstalling. If the hosted
+installer is temporarily unavailable, the
+installer can still fall back to an authenticated GitHub CLI or
+`GITHUB_TOKEN`/`GH_TOKEN` with read access to `manintheandes/ask-just`.
+
+On success, the installer prints the welcome message and stops:
+
+```text
+Ask Just is how you have a conversation with the company.
+```
+
+For manual employee setup parity checks, run the local doctor after install:
+
+```bash
+export PATH="$HOME/.local/bin:$PATH"
+ask-just doctor
+```
+
+The doctor checks the installed `ask-just` binary, PATH, local config, hosted
+readiness, hosted source inventory, and Codex skills (`askjust`, `just-source`,
+`correction`, and `braintrust`) without printing the bearer token. It returns
+`ok: true`, `status: ready`, and an empty `required_gaps` list only when the
+standard Ask Just setup is ready.
+
+Do not use NetSuite, SQL, revenue, transactions, items, or any other business
+source as part of employee setup verification.
+
+Then ask source-backed questions:
+
+```bash
+export PATH="$HOME/.local/bin:$PATH"
+ask-just doctor
+ask-just health --deep
+ask-just summary
+ask-just sources
+ask-just --include-trace query "Mar gross revenue" --source scorecard_monthly_data --kind atomic --limit 3
+ask-just query "WALMART CORP RMA IMPOSSIBLE dollars" --source spins_plant_based_meat_powertabs --kind atomic --limit 6
+ask-just query "Protein on Hold mar" --source scorecard_ops_metrics --kind atomic --limit 3
+ask-just query "held batches" --source batch_release_app --kind atomic --limit 6
+ask-just personal-mail-status
+ask-just personal-mail-search "Publix" --days 30 --limit 10
+ask-just query "customrecord outlook sync part tracker" --source netsuite_account_catalog --kind atomic --limit 5
+ask-just query "Mung Bean" --source netsuite_items --kind atomic --limit 8
+ask-just query "March 2026 net revenue" --source netsuite_pnl_monthly --kind atomic --limit 5
+ask-just query "open AR invoices" --source netsuite_ar_open_invoices --kind atomic --limit 5
+ask-just query "open AP bills" --source netsuite_ap_open_bills --kind atomic --limit 5
+ask-just query "inventory on hand" --source netsuite_inventory_snapshot --kind atomic --limit 5
+ask-just sql "select received_date, primary_intent, subject from wecare_customer_issue_summaries where is_refund_request = 1 order by received_date_time desc limit 5"
+ask-just sql "select count(*) as n from atomic_rows"
+```
+
+For normal teammate use, `ask-just query` is the question surface. `ask-just
+search` is a raw keyword diagnostic for source debugging, not something a
+teammate should have to choose when asking a business question.
+
+Fresh source lanes:
+
+```bash
+python3 scripts/build_strict_source_completion_table.py
+python3 scripts/build_source_required_inputs.py
+python3 scripts/check_vm_source_refresh_status.py
+python3 scripts/verify_source_goal_complete.py
+ask-just health --deep
+ask-just query "Mar gross revenue" --source scorecard_monthly_data --kind atomic --limit 3
+ask-just query "PUBLIX CORP RMA JUST Egg Plant Based Scramble 16 Oz 4.2" --source spins_breakfast_powertabs --kind atomic --limit 1
+```
+
+The WECARE mailbox lane refreshes daily from Microsoft Graph over the rolling
+last 30 days for `wecare@ju.st` across inbox, archive, sent items, deleted
+items, and junk. It writes message rows, attachment metadata, mailbox metrics,
+and typed `wecare_customer_issue_summaries` rows for refund, spoilage, shipping,
+contact-form, product complaint, product-term, retailer, and sender-domain
+queries.
+
+The CLI returns JSON so Codex, Claude Code, shell scripts, and future dashboards
+can consume the same source evidence reliably.
+
+## How Corrections Improve Ask Just
+
+When Ask Just gives a weak answer, the fix should become part of the system, not
+just part of one chat. There are three places to make that correction.
+
+### 1. Fix the agent instructions
+
+Update the `$askjust` skill when Codex or Claude misunderstood the question or
+chose the wrong source.
+
+Example: if someone asks for current KPIs, the skill should route to Scorecard
+current truth through hosted Ask Just or say the hosted source index only has
+routing/proof records, instead of treating narrative context as exact current
+metrics.
+
+### 2. Fix the shared rulebook
+
+Update the README or spec when the rule should be visible to everyone working on
+Ask Just.
+
+Example: velocity should use SPINS last 4 weeks by default, with HEB and Whole
+Foods as explicit retailer-specific exceptions. The spec should name the exact
+boundary and require it to be rebuilt into SQLite so future agents do not fall
+back to the retailer review calendar/reset tracker, stale Scorecard, or generic
+context. The `target_tracker` source id is a workbook for retailer review
+calendars and resets; it is not Target customer evidence.
+
+For SPINS velocity, the first answer path is the structured visible PowerTabs
+`Item` / Item Ranking report table, `spins_item_ranking_rows`. Decoded
+`pivot_cache_records` are supporting or fallback evidence; a pivot-cache miss is
+not a source miss when the visible report row exists.
+
+When reproducing a PowerTabs report manually, the stable path is: open the
+right workbook, go to `Item`, use `Geo` as the retailer/geography selector,
+choose the time period, then choose the category and subcategory that match the
+SKU family. For breakfast, JUST Egg liquid is `REFRIGERATED EGGS` /
+`RF EGGS LIQUID`; JUST Egg Folded and burritos are in
+`FROZEN BREAKFAST FOODS` with the matching frozen breakfast subcategory. An
+incompatible category/subcategory slicer state can hide valid rows and must be
+cleared or corrected before treating the result as a source gap.
+
+The durable SPINS target is a standard all-period Item Ranking slice layer, not
+an ad hoc currently-open Excel view. For each relevant SPINS workbook,
+materialize `4 Weeks`, `12 Weeks`, `24 Weeks`, and `52 Weeks` Item Ranking rows
+for `MULO`, `NATURAL`, and every retailer/geography listed in SPINS. Preserve
+every visible SKU row, including competitors, across the frozen breakfast,
+refrigerated eggs, meat, protein powder, and condiment workbooks. Unit velocity
+is `Average Weekly Units Per Store Selling Per Item`; dollar velocity or
+dollars per door per week is `Average Weekly Dollars Per Store Selling Per
+Item`. If the user does not specify a period, answer velocity from `4 Weeks` by
+default.
+
+If Excel is showing a recovered or newly filtered PowerTabs state, capture that
+visible report before rebuilding:
+
+```bash
+python3 scripts/capture_spins_visible_item_ranking.py --source-id spins_breakfast_powertabs
+python3 scripts/build_fresh_source_database.py --source-id spins_breakfast_powertabs
+```
+
+The capture writes `*.visible-item-ranking.json` under
+`source-material/<source-id>/visible-item-ranking-snapshots/`, and the builder
+ingests every captured view into `spins_item_ranking_rows` with Excel-visible
+report provenance.
+
+### 3. Fix the tool
+
+Add or improve a CLI/API command when the same question will come up again and
+should not depend on a fresh ad hoc SQL query each time.
+
+Example: if revenue or velocity questions become common, add named commands that
+always use the right source id, table, filters, and provenance rules.
+
+For most Just teammates, the workflow stays simple: ask through Codex, Claude,
+or another agent and inspect the evidence. Power users can also use the local
+CLI directly. Everyone benefits when recurring corrections are captured in
+these shared layers.
+
+## Hosted Service
+
+Ask Just now has a small shared VM host, and the same service can still run locally for development.
+
+| Piece | Value |
+| --- | --- |
+| GCP project | `ask-just-prod` |
+| VM | `ask-just-server` in `us-central1-a` |
+| VM repo | `/home/josh/ask-just` |
+| Local repo | `/Users/josh/projects/ask-just` |
+| Private VM service | `http://127.0.0.1:8792` |
+| Public HTTPS endpoint | `https://ask-just.35.222.146.245.sslip.io` |
+| SQLite index | `artifacts/ask-just-fresh-source-plane/source_index.sqlite` |
+| Builder | `scripts/build_fresh_source_database.py` |
+| CLI client | `ask-just` / `scripts/ask_just.py` |
+| Service unit | `deploy/systemd/ask-just.service` |
+| Daily refresh units | `deploy/systemd/ask-just-source-refresh.service` / `deploy/systemd/ask-just-source-refresh.timer` |
+
+The Python service is read-only and bound to localhost on the VM. Public traffic
+enters through HTTPS and bearer-token auth, then nginx proxies to the private
+localhost service.
+
+The SQLite index lives at:
+
+```text
+/home/josh/ask-just/artifacts/ask-just-fresh-source-plane/source_index.sqlite
+```
+
+That database is the answer-data artifact. It is generated runtime state, so the
+durable repo assets are the maps, parser code, receipts, and tests that rebuild
+and verify it. Promote staged rebuilds to the VM only after health, count, gap,
+hash, and query checks pass.
+
+Build the SQLite index:
+
+```bash
+python3 scripts/build_fresh_source_database.py
+```
+
+Run the local HTTP server:
+
+```bash
+python3 scripts/serve_http.py --host 127.0.0.1 --port 8792
+```
+
+Install or refresh the VM service:
+
+```bash
+sudo install -m 0644 deploy/systemd/ask-just.service /etc/systemd/system/ask-just.service
+sudo systemctl daemon-reload
+sudo systemctl enable --now ask-just.service
+```
+
+Install or refresh the VM daily source-refresh automation:
+
+```bash
+sudo install -d -m 0750 /etc/ask-just
+sudo install -m 0600 deploy/systemd/source-refresh.env.example /etc/ask-just/source-refresh.env
+sudoedit /etc/ask-just/source-refresh.env
+sudo install -m 0644 deploy/systemd/ask-just-source-refresh.service /etc/systemd/system/ask-just-source-refresh.service
+sudo install -m 0644 deploy/systemd/ask-just-source-refresh.timer /etc/systemd/system/ask-just-source-refresh.timer
+sudo systemctl daemon-reload
+sudo systemctl start ask-just-source-refresh.service
+sudo systemctl enable --now ask-just-source-refresh.timer
+systemctl list-timers ask-just-source-refresh.timer
+```
+
+The timer runs daily at midnight America/Los_Angeles on the VM. Non-SPINS lanes use Graph
+delta, source API cursors, HTTP validators, modified time, or hash-delta as
+appropriate. The WECARE mailbox lane refreshes daily from Microsoft Graph over
+the rolling last 30 days for `wecare@ju.st` across inbound customer-signal
+folders. It intentionally does not source sent replies, junk, WECARE-authored
+mail, admin notifications, vendor pitches, conference/hotel spam, or other
+non-customer mailbox noise. Its typed table `wecare_customer_issue_summaries`
+tags refund, spoilage, shipping, contact-form, product complaint, product-term,
+retailer, and sender-domain fields for customer-signal CX questions. Asana is a key
+work-management source lane: it requires token-backed active and archived
+project enumeration for catalog facts, plus rolling 30-day task activity for
+selected source teams and explicit source projects. Rolling modified-task rows
+are current work-item evidence, while project catalog rows remain the source for
+old named project existence/owner/team/link questions. SPINS lanes remain delivered
+workbook snapshots until a new workbook delivery is persisted under
+`source-material/`.
+
+`/etc/ask-just/source-refresh.env` must contain one supported Microsoft Graph
+credential shape for Graph-backed lanes: `MS_TENANT_ID`,
+`MS_GRAPH_CLIENT_ID`, and `MS_GRAPH_CLIENT_SECRET`; the previous
+order-allocation `GRAPH_TENANT_ID`, `GRAPH_CLIENT_ID`, and
+`GRAPH_CLIENT_SECRET` shape; or delegated `GRAPH_TENANT_ID`,
+`GRAPH_CLIENT_ID`, and `GRAPH_REFRESH_TOKEN`. Do not mark the source goal
+complete unless `python3 scripts/verify_source_goal_complete.py` is green after
+the VM refresh service succeeds.
+
+## Personal Source Overlay
+
+Ask Just can let one bearer token unlock both the shared company source plane
+and that user's private Microsoft Graph mailbox. This is intentionally not a
+shared source lane: personal mailbox rows are queried live through delegated
+Graph access and are not written into the shared SQLite index.
+
+The server reads an optional registry from `ASK_JUST_PERSONAL_SOURCES`, usually
+`/etc/ask-just/personal-sources.json`. Each registry entry maps a SHA-256 hash
+of a user's Ask Just bearer token to that user's mailbox and env-var names for
+delegated Graph credentials. Use
+`deploy/systemd/personal-sources.example.json` and
+`deploy/systemd/http.env.example` as the install templates.
+
+To compute the registry hash for the current configured Ask Just token:
+
+```bash
+ask-just token-hash
+```
+
+Personal mailbox commands:
+
+```bash
+ask-just personal-mail-status
+ask-just personal-mail-search "Lisa Publix" --days 30 --limit 10
+ask-just personal-mail-read "<message-id>"
+ask-just personal-mail-draft --to "person@example.com" --subject "Subject" --body "Draft body"
+ask-just personal-mail-reply-draft "<message-id>" --body "Reply draft body"
+ask-just personal-mail-send-draft "<draft-message-id>"
+```
+
+Privacy rule: company sources are shared; personal sources inherit the ACL of
+the token owner and are visible only to that mapped bearer token. Actual
+delivery is intentionally a separate `personal-mail-send-draft` command; normal
+write operations create drafts.
+
+Health check:
+
+```bash
+ask-just health --deep
+```
+
+Source-specific hosted proof:
+
+```bash
+ask-just query "Protein on Hold mar" --source scorecard_ops_metrics --kind atomic --limit 3
+ask-just query "held batches" --source batch_release_app --kind atomic --limit 6
+ask-just query "customrecord outlook sync part tracker" --source netsuite_account_catalog --kind atomic --limit 5
+ask-just query "Mung Bean" --source netsuite_items --kind atomic --limit 8
+```
+
+The VM service and laptop tunnel were verified on 2026-05-02 for
+`scorecard_ops_metrics`: `Protein on Hold mar` returns field-level provenance
+for `Upstream Inventory:Protein on Hold (MT):mar` with value `46`.
+The local Batch Release ask surface was verified on 2026-05-03:
+`held batches` returns field-level provenance for Batch Release records, with
+6 held status rows in the current app-state read-data snapshot.
+The NetSuite account catalog audit lane was verified on 2026-05-04:
+`vendorBill suiteql row count` returns `netsuite_record_type_catalog`, and
+`customrecord outlook sync part tracker` returns
+`netsuite_metadata_catalog_root_items` from the root metadata catalog.
+The VM NetSuite item source was verified on 2026-05-02: the VM rebuilt from
+live SuiteQL using its private `NETSUITE_*` environment file, and `Mung Bean`
+returns field-level provenance from `netsuite:/suiteql/item`.
+
+See [docs/local-http-service.md](docs/local-http-service.md) and
+[docs/remote-cli.md](docs/remote-cli.md).
+
+## Codex Skills
+
+This repo owns the Codex skills that make the experience feel like asking the
+company rather than running a database query:
+
+```text
+skills/askjust/SKILL.md
+skills/braintrust/SKILL.md
+skills/correction/SKILL.md
+skills/just-source/SKILL.md
+```
+
+`just-source` defines when a Just artifact becomes source-grade. `$askjust` is
+the conversational front door over source-grade Just memory. `correction`
+defines what to do when an Ask Just answer needs a durable routing or answer
+fix. `braintrust` defines the Ask Just trace inspection and verification
+workflow.
+
+## Source Links
+
+Ask Just answers still come from the hosted API backed by the verified GCP VM
+SQLite source index. Source links are an inspection layer over that evidence:
+rows with `provenance_grain` are enriched with `source_links`, and the same
+resolver is available directly:
+
+```bash
+ask-just source-links --source-id spins_plant_based_meat_powertabs \
+  --locator "/Users/josh/Downloads/SPINS PowerTabs Eat Just Plant Based Meat Data Ending 04-19-26 (1).xlsb#sheet=Retailer&row=16"
+```
+
+The resolver uses hosted source-index tables such as `atomic_rows`,
+`source_files`, and source provenance to return the upstream artifact handle:
+local workbook paths, HTTP/API URLs, or structured locators such as
+`netsuite:/suiteql/...`. Links are for source inspection and trust; they do not
+replace the hosted API as the normal answer path.
+
+Verify link coverage for the currently built SQLite plane with:
+
+```bash
+python3 scripts/audit_source_links.py
+```
+
+## Braintrust Tracing
+
+Ask Just query requests emit Braintrust traces when the runtime has the Python
+dependency and an API key:
+
+```bash
+python3 -m venv .venv
+. .venv/bin/activate
+python3 -m pip install -r requirements.txt
+export BRAINTRUST_API_KEY=...
+export ASK_JUST_BRAINTRUST_PROJECT=ask-just
+export ASK_JUST_BRAINTRUST_PROJECT_ID=2a580ddb-dbad-4acd-a8b7-eacc2ab91123
+```
+
+Tracing fails open: if the SDK or API key is missing, source queries still run
+and simply omit trace fields. The CLI does not trace ordinary calls, so source
+answers stay fast and provenance is not mixed with observability metadata. Use
+`--include-trace` or `--open-trace` when debugging a run. The local Braintrust
+context is stored in `.bt/config.json`.
+
+Runtime tracing is non-blocking by default so CLI answers are not delayed by
+Braintrust network flushes. For a debugging session that must wait until trace
+events are uploaded, set `ASK_JUST_BRAINTRUST_SYNC_FLUSH=1`. To force tracing
+for every hosted request, set `ASK_JUST_BRAINTRUST_TRACE_ALL=1`.
+
+## Source Plane
+
+- Source plane id: `ask_just_fresh_source_plane`
+- Active source map: [config/fresh-source-map.yaml](config/fresh-source-map.yaml)
+- Parser: `scripts/build_fresh_source_database.py`
+- Query helper: `ask-just`
+- Local rebuild index: `artifacts/ask-just-fresh-source-plane/source_index.sqlite`
+- VM index: `/home/josh/ask-just/artifacts/ask-just-fresh-source-plane/source_index.sqlite`
+- Receipts: `receipts/fresh/`
+
+## Repo Layout
+
+```text
+config/fresh-source-map.yaml                   Active fresh Ask Just source-lane map
+config/source-map.yaml                         Active wrapper map for the fresh source plane
+config/queryable-source-ids.json               Canonical queryable source ids
+receipts/fresh/                                Machine-readable receipts for active lanes
+docs/source-receipts/                          Human-readable receipt summaries
+artifacts/ask-just-fresh-source-plane/         Generated local rebuild artifacts
+scripts/build_fresh_source_database.py         Fresh source-index builder
+scripts/serve_http.py                          Read-only local HTTP API
+scripts/ask_just.py                            CLI client
+install.sh                                     One-line installer for ~/.local/bin/ask-just
+skills/askjust/SKILL.md                        Codex routing skill
+```