ask-just 0.1.0

Thin CLI for the hosted Ask Just source plane

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:

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:

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 for the deeper product contract and future direction. Read docs/ask-just-model-card.md for the model card and docs/ask-just-release-notes.md for release history. Read 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 for the phase audit behind the current source-plane claim. Read 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.

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.

sips -s format png docs/ask-just-architecture.svg --out docs/ask-just-architecture.png

Use these visuals to explain product boundaries like:

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:

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:

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:

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 [e-mail] plus Inventory Stock Summary Report; Bethlehem defaults to [e-mail] 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:

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:

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 -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:

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:

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:

Ask Just is how you have a conversation with the company.

For manual employee setup parity checks, run the local doctor after install:

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:

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:

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 [e-mail] 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:

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:

/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:

python3 scripts/build_fresh_source_database.py

Run the local HTTP server:

python3 scripts/serve_http.py --host 127.0.0.1 --port 8792

Install or refresh the VM service:

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:

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 [e-mail] 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:

ask-just token-hash

Personal mailbox commands:

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 "[e-mail]" --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:

ask-just health --deep

Source-specific hosted proof:

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 and 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:

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:

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:

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:

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
• 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

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