Skip to main content

Quick Start

Human interface repository for the Helpifyr stack.

It provides a contract-based, user-facing shell for Helpifyr modules without creating shadow truth for upstream owners.

Helpifyr Lantern

Purpose​

jhf-lantern provides the user-facing interface baseline for Helpifyr products and stack modules.

Devpost Repository And AI Use​

  • Repository: JaddaHelpifyr/jhf-lantern
  • AI-assisted development: OpenAI Codex and GPT-5.6 were used as engineering assistants for issue triage, implementation and documentation drafting, focused test and verification work, and PR-review support. Repository contracts, CI, owner boundaries, and human approval gates remain the source of truth for delivery decisions.
  • Evaluator access: This repository is private. Access for Devpost evaluation has been granted to testing@devpost.com and build-week-event@openai.com.

Current State​

  • repository scaffold initialized
  • contract and docs baseline initialized
  • the real v0-optimized operator dashboard is the active UI entry in src/lantern_ui/
  • Fabric OSS upgrade consumer adoption with fail-closed verification is active
  • operator-lane recovery consumer boundary is active with explicit fail-closed upstream blocker posture
  • Phase-0 read-only Lantern WebUI shell and BFF artifacts are present
  • Plan Studio now renders an admitted operator-ready consumer surface with real sessions, review/score/evidence readback, program-graph posture, and explicit readback-only action posture
  • Plan Studio also exposes a hardened Phase-0.5 Compose tab shell in fixture/future_contract mode with explicit state coverage and no local plan-studio write lane
  • visible sidebar and header posture now follow a repo-owned route posture registry so admitted/live, restricted, preview, and future routes stay honest
  • Operations route includes CI-facing operator cards, repo drilldown, runner inventory, and cutover posture
  • bootstrap setup remains Lantern-owned only as wizard, admin, and readback UX; business truth, approval truth, and final closeout stay upstream
  • W1 bootstrap onboarding keeps company/country/industry/size/accounting/organization/access/residency profile families explicit and preserves quickstart versus full mode posture without local shadow truth

Quick Start​

python scripts/run_pnpm.py install
python scripts/run_pnpm.py dev

If a local or CI environment must avoid automatic system-CA injection, set LANTERN_NODE_USE_SYSTEM_CA=off before invoking scripts/run_pnpm.py.

Open: http://<internal-runtime-redacted>:4173

Local Preview​

Fixture mode is the default local UX so the UI can boot without Fabric, Pattern, or Gitea dependencies.

python scripts/run_pnpm.py build
python scripts/run_pnpm.py preview

Preview runs on http://<internal-runtime-redacted>:4173.

Public Static Preview​

The anonymous public preview compiles the current src Lantern app shell against dedicated compile-time fixture adapters. It retains the private app's sidebar, header, navigation, and read-only surface structure while containing no backend, login, runtime readback, or action lane. Public navigation uses static hash routes so operator-only paths remain fail-closed:

python scripts/run_pnpm.py verify:public-preview

See docs/DEPLOYMENT.md for the Pages deployment boundary.

Filtered Pages Artifact​

Create a public Pages artifact only from a clean local checkout at exact origin/main; this does not publish canonical Gitea history:

python scripts/create_filtered_publication_bundle.py --output-dir <empty-external-artifact-directory>
python scripts/verify_filtered_publication_bundle.py --artifact-dir <empty-external-artifact-directory>

Local Live Mode​

Use live mode only when you want contract-backed readbacks from the repo-owned BFF.

  1. Copy .env.example to .env.local
  2. Set:
VITE_LANTERN_DATA_MODE=live
VITE_LANTERN_API_BASE_URL=`api/v`1/lantern
  1. Start the BFF in a second terminal:
python scripts/run_pnpm.py dev:bff
  1. Start the UI:
python scripts/run_pnpm.py dev:live

The wrapper keeps pnpm canonical while opting Node into the local system CA store. This avoids UNABLE_TO_VERIFY_LEAF_SIGNATURE on managed Windows hosts without weakening TLS verification.

For repo-backed Gitea issue and PR detail in live mode or deployed runtime, provide GITEA_TOKEN in the repo root .env. GITEA_BASE_URL defaults to https://code.example.invalid and should be set explicitly for live/private deployments.

For auth-bound HITL Inbox, Approvals, and other owner-backed upstream readbacks, provide the repo-owned bearer tokens in the same .env when those upstreams are guarded:

  • FABRIC_API_TOKEN for helpifyr-fabric readback routes
  • WARP_API_TOKEN for jhf-warp owner-decision readback and submit routes
  • PATTERN_API_TOKEN for auth-bound jhf-pattern projections

For live owner-host materialization, scripts/materialize_live_runtime.sh is fail-closed. It resolves auth input from LANTERN_RUNTIME_AUTH_ENV, repo .env, or ~/.config/helpifyr/runtime-secrets/lantern-runtime-auth.env and refuses to deploy if GITEA_TOKEN, FABRIC_API_TOKEN, WARP_API_TOKEN, or PATTERN_API_TOKEN are missing or empty.

Release Eligibility Posture​

  • Public release-surface admission is bounded by contracts/admission/release_surface_inventory_v1.json.
  • Current repository history posture is tracked in contracts/admission/repository_publication_history_posture_v1.json.
  • Active owner blocker: JaddaHelpifyr/jhf-lantern#382.
  • jhf-lantern remains pending_history_scan; this slice prepares and tests public release surfaces only and does not authorize publication.
  • Repo-owned history evidence now runs through python scripts/verify_repository_history_posture.py and currently proves filtered_publication_required.
  • Canonical Gitea history remains private or internal; any future public candidate is filtered publication from exact main, never a rewrite of canonical history.
  • The owner decision is recorded in docs/FILTERED_PUBLICATION_DECISION.md.

Screenshot And Preview Hints​

  • For stable screenshots, stay in fixture mode and open:
    • http://<internal-runtime-redacted>:4173/
    • http://<internal-runtime-redacted>:4173/quality
    • http://<internal-runtime-redacted>:4173/operations
  • Fixture preview is explicitly marked in the active v0 shell so production and preview states are not confused.
  • Live mode is only needed when you want to verify real /api/v1/lantern/* readbacks.

Documentation​

  • docs/ARCHITECTURE.md
  • docs/HUMAN_INTERFACE_MODEL.md
  • docs/LANTERN_MVP.md
  • docs/OVERVIEW.md
  • docs/CAPABILITIES.md
  • docs/API_CONSUMPTION_CONTRACT.md
  • docs/NAVIGATION_REGISTRY.md
  • docs/UI_INFORMATION_ARCHITECTURE.md
  • docs/NON_GOALS.md
  • PLAN_LANTERN_PLAN_STUDIO_PHASE0_5.md
  • runtime/lantern/plan-studio-compose-source-contract-matrix.v1.json
  • docs/THIRD_PARTY_UI_REUSE.md
  • docs/REFERENCE_TO_LANTERN_MAPPING.md
  • docs/DEPLOYMENT.md
  • docs/LIVE_VERIFY.md
  • docs/OPERATIONS.md
  • docs/REFERENCE_UI_INVENTORY.md
  • docs/STACK_CONTRACT.md
  • docs/contracts/JHF_LANTERN_UI_SHELL_CONTRACT.md
  • docs/FABRIC_TOOL_PROFILE.md
  • docs/FABRIC_OSS_UPGRADE_CONSUMER.md
  • docs/FABRIC_OPERATOR_LANE_CONSUMER.md

Scan&Fix Quick Start​

bash scripts/scan_and_fix.sh --dry-run
bash scripts/scan_and_fix.sh --dry-run --all-open

See docs/OPERATIONS.md for the full Scan&Fix runbook.

License: AGPLv3 Project: https://helpifyr.com

License​

Copyright (C) 2025-2026 ANYFER GmbH. Licensed under the GNU Affero General Public License v3.0 only (AGPL-3.0-only) -- see LICENSE (LICENSE).

This project connects unmodified third-party open-source components; no such component is redistributed, rebranded, or claimed as ANYFER's own work. See THIRD_PARTY_NOTICES.md (THIRD_PARTY_NOTICES.md) for a component-level list. All third-party product names, logos, and trademarks remain the property of their respective owners; no affiliation or endorsement by those owners is implied.

Trademark, AGPLv3 scope, and legal boundary: anyfer.com/legal. Learn more at helpifyr.com.