Build [v1.9.19]

.agent/rules/superpowers.md

@@ -0,0 +1,55 @@
+# Superpowers Rules (Always-On)
+
+These rules apply to ALL work unless the user explicitly opts out.
+
+## 1) Plan gate for non-trivial work
+If the task is anything beyond a tiny change, do NOT edit code immediately.
+You MUST:
+1) Brainstorm briefly (goal, constraints, risks, acceptance criteria)
+2) Write a step-by-step plan with verification steps
+3) Ask the user to approve the plan
+Only after approval may you implement.
+
+### Execute-plan gate (Superpowers parity)
+After the user approves a plan, do NOT begin implementation automatically.
+You MUST pause and instruct the user to run: `/superpowers-execute-plan`
+
+Only begin implementation after `/superpowers-execute-plan` is invoked,
+unless the user explicitly says to proceed without it.
+
+### What counts as "tiny"?
+- single-file change
+- obvious edit
+- low risk
+Even then: do a mini-plan (3–5 steps) and include verification.
+
+## 2) Verification is mandatory
+After implementation, you MUST provide:
+- exact commands to verify (tests/lint/run)
+- and results if you were able to run them
+
+## 3) Prefer TDD / regression tests
+- If fixing a bug: add a regression test if practical
+- If adding behavior: add/adjust tests when practical
+If tests aren’t feasible, provide a concrete alternative verification path.
+
+## 4) Review pass required
+Before final response, do a review pass and list issues by severity:
+- Blocker / Major / Minor / Nit
+
+## 5) Safety
+- Never log secrets
+- Add timeouts, retries, and idempotency for API automations
+- Fail safe (no silent data loss)
+
+## Artifact persistence (mandatory)
+Any brainstorm, plan, review, or finish output must be written to disk under:
+`artifacts/superpowers/`
+
+Do not leave these as IDE-only documents.
+After writing, confirm the file exists.
+
+## Persistence enforcement
+When a workflow requires saving an artifact to `artifacts/superpowers/`, you MUST ensure the file exists on disk.
+Preferred method: use `python .agent/skills/superpowers-workflow/scripts/write_artifact.py --path <...>`.
+If you cannot execute commands, instruct the user to save the output manually.

.agent/skills/superpowers-brainstorm/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: superpowers-brainstorm
+description: Produces a structured brainstorm: goals, constraints, risks, options, recommendation, and acceptance criteria. Use before non-trivial implementation or design changes.
+---
+
+# Brainstorm Skill
+
+## When to use this skill
+- before implementing non-trivial features
+- before refactors with unclear scope
+- before debugging complex issues
+- before designing an automation workflow
+
+## Brainstorm template (use this exact structure)
+### Goal
+- (1–2 sentences)
+
+### Constraints
+- (tech stack, time, compatibility, performance, “must not change”, etc.)
+
+### Known context
+- (what exists today; relevant files/components; current behavior)
+
+### Risks
+- (security, data loss, regressions, surprising side effects)
+
+### Options (2–4)
+For each option include:
+- Summary
+- Pros / cons
+- Complexity / risk
+
+### Recommendation
+- Pick one option and explain why
+
+### Acceptance criteria
+- Bullet list of verifiable outcomes

.agent/skills/superpowers-debug/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: superpowers-debug
+description: Systematic debugging: reproduce, isolate, form hypotheses, instrument, fix, and add regression tests. Use when troubleshooting errors, failing tests, or unexpected behavior.
+---
+
+# Debug Skill
+
+## When to use this skill
+- runtime errors, flaky tests, wrong outputs
+- “it used to work” regressions
+- performance or timeout problems (initial triage)
+
+## Debug workflow (do not skip steps)
+1. **Reproduce**
+   - Capture exact error, inputs, environment, command.
+2. **Minimize**
+   - Reduce to smallest repro (one file, one function, smallest dataset).
+3. **Hypotheses (2–5)**
+   - Rank by likelihood.
+4. **Instrument**
+   - Add temporary logging/assertions or use existing diagnostics.
+5. **Fix**
+   - Smallest change that removes root cause.
+6. **Prevent**
+   - Add regression test or permanent guard/validation.
+7. **Verify**
+   - Run the failing case + relevant suites.
+
+## Reporting format
+- Symptom
+- Repro steps
+- Root cause
+- Fix
+- Regression protection
+- Verification

.agent/skills/superpowers-finish/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: superpowers-finish
+description: Finalizes work: runs verification, summarizes changes, notes follow-ups, and ensures repo hygiene. Use at the end of an implementation or debugging session.
+---
+
+# Finish Skill
+
+## When to use this skill
+- at the end of any non-trivial change set
+- after a bug fix or feature is implemented
+- before handing off work to a teammate/user
+
+## Finish checklist
+- Run verification commands (tests, lint, build, typecheck if relevant)
+- Confirm acceptance criteria are met
+- Summarize what changed (by area/file)
+- Call out any risks or follow-ups
+- Note how to rollback if applicable
+
+## Output format
+### Verification
+- Commands run:
+- Results:
+
+### Summary of changes
+- Bullet list
+
+### Follow-ups
+- Bullet list (only if needed)
+
+### How to validate manually (if applicable)
+- Steps

.agent/skills/superpowers-plan/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: superpowers-plan
+description: Writes an implementation plan with small steps, exact files to touch, and verification commands. Use before making non-trivial changes.
+---
+
+# Planning Skill
+
+## When to use this skill
+- any multi-file change
+- any change that impacts behavior, data, auth, billing, or production workflows
+- any debugging that needs systematic isolation
+
+## Planning rules
+- Steps should be **small** (2–10 minutes each).
+- Every step must include **verification**.
+- Prefer **incremental deliverables** (avoid “big bang” edits).
+- Identify **rollback** and **risk controls** early.
+
+## Plan format (use this exact structure)
+### Goal
+### Assumptions
+### Plan
+1. Step name
+   - Files: `path/to/file.ext`, `...`
+   - Change: (1–2 bullets)
+   - Verify: (exact commands or checks)
+2. ...
+
+### Risks & mitigations
+### Rollback plan

.agent/skills/superpowers-python-automation/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: superpowers-python-automation
+description: Implements reliable automations in Python for REST APIs: httpx/requests patterns, retries, timeouts, pagination, typing, config, logging, and tests. Use when writing Python scripts/services that call external APIs.
+---
+
+# Python Automation Skill
+
+This skill provides concrete Python patterns to implement robust REST API automations.
+
+## When to use this skill
+- Python scripts that call one or more REST APIs
+- ETL jobs, sync tools, webhook handlers
+- CLI tools or small services that integrate external systems
+
+## Preferred stack (defaults)
+- HTTP client: **httpx** (preferred) or requests
+- Config: env vars + `.env` (optional) with pydantic-settings if appropriate
+- Logging: stdlib `logging` with structured-ish fields
+- Testing: pytest (+ respx for httpx mocking when useful)
+
+If the project already uses different tools, follow project conventions.
+
+---
+
+## Reference architecture (small but scalable)
+- `client.py`: API client wrapper (auth headers, retries, pagination helpers)
+- `models.py`: typed payload models (dataclasses or pydantic)
+- `sync.py`: orchestration logic (fetch -> transform -> upsert)
+- `main.py`: CLI entrypoint
+- `tests/`: unit tests for transform + client behavior
+
+## HTTP rules (mandatory)
+- Always set timeouts (connect + read)
+- Centralize request sending in one function so retries/logging are consistent
+- Never log secrets (Authorization headers, tokens)
+
+### Retry policy guidance
+Retry on:
+- network errors/timeouts
+- 429 (respect Retry-After when present)
+- 500–599
+Optional: 408, and 409 only if operation is safe and semantics known
+
+Do NOT retry on:
+- most 400–499 (unless explicitly safe)
+
+### Timeouts
+- Set explicit timeouts; do not rely on defaults.
+- Use smaller connect timeout; moderate read timeout.
+
+---
+
+## Pagination patterns
+Support at least one helper that can handle:
+- `next` URL in response
+- cursor token in response
+- page/limit parameters
+
+Add a hard stop:
+- max pages OR max items OR max elapsed time
+
+---
+
+## Idempotency patterns (Python)
+Choose and document:
+- Use an `Idempotency-Key` header when supported
+- Upsert using a stable `external_id`
+- Persist a lightweight state store:
+  - simplest: SQLite file (recommended for OSS)
+  - alternative: JSONL log + compaction
+
+Minimum: ensure repeated runs don’t create duplicates.
+
+---
+
+## Observability (Python)
+Minimum logs should include:
+- `run_id`
+- request: method, url/path, status_code, elapsed_ms, attempt
+- record counts: processed/created/updated/skipped/failed
+
+Also include a final summary log line.
+
+---
+
+## Verification requirements
+For non-trivial work, add:
+- unit tests for mapping/transform logic
+- at least one test for pagination or retry behavior (mocked)
+- a “dry-run” CLI flag (prints intended writes)
+
+---
+
+## Output format when writing code
+- Provide a small directory layout
+- Explain how to configure env vars
+- Include exact commands to run (and test)

.agent/skills/superpowers-rest-automation/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: superpowers-rest-automation
+description: Builds reliable automations that integrate with REST APIs: auth, pagination, retries, rate limits, idempotency, webhooks, data mapping, and safe error handling. Use when calling external APIs, syncing systems, or building ETL-style workflows.
+---
+
+# REST Automation Skill
+
+This skill enforces reliability and safety when building automations that call REST APIs.
+
+## When to use this skill
+Use whenever the task involves:
+- calling external REST APIs (CRUD, search, sync)
+- integrating 2+ systems (ETL, iPaaS-like flows)
+- webhooks, polling, or scheduled jobs
+- data ingestion, normalization, enrichment, deduplication
+
+## Default design principles
+- **Idempotent by design**: repeats should not create duplicates or corrupt data.
+- **Observable**: logs/metrics correlate each run and each API call.
+- **Fail safe**: handle partial failures; avoid silent data loss.
+- **Rate-limit aware**: backoff and respect vendor limits.
+- **Least privilege**: handle secrets safely, avoid overbroad scopes.
+
+---
+
+## Checklist (apply unless irrelevant)
+
+### 1) Define the contract
+- Inputs (format, required fields, validation)
+- Outputs (where data goes, expected shape)
+- Success criteria (what “done” means)
+- Non-goals (what the automation will not do)
+
+### 2) Authentication & secrets
+- Identify auth type: API key, OAuth2, JWT, mTLS
+- Never hardcode secrets in code or logs
+- Support secret injection via env vars / secret manager
+- Plan token refresh if applicable (OAuth2)
+
+### 3) Idempotency & deduplication
+Pick at least one:
+- Use provider idempotency keys (if supported)
+- Use stable external IDs (e.g., `external_id` field) for upserts
+- Keep a local/state store mapping source IDs -> target IDs
+- Use deterministic hashes for dedupe when no stable ID exists
+Document the idempotency strategy explicitly.
+
+### 4) Pagination & incremental sync
+- Detect pagination style: `next` link, cursor, page+limit, offset+limit
+- Ensure loops terminate safely (max pages / max time)
+- Prefer incremental sync using `updated_since`/ETag/If-Modified-Since when possible
+- Handle out-of-order updates and late-arriving events
+
+### 5) Retries, backoff, and timeouts
+- Set **timeouts** for connect/read
+- Retry on transient errors: network failures, 429, 5xx (with limits)
+- Use exponential backoff with jitter if possible
+- Do **not** retry on most 4xx (except 408/409/429 depending on semantics)
+- Cap retries and surface failures clearly
+
+### 6) Rate limits & quotas
+- Respect `Retry-After` and rate-limit headers
+- Implement adaptive backoff on 429
+- Consider batch endpoints to reduce call volume
+- Avoid bursty concurrency unless explicitly safe
+
+### 7) Data mapping & validation
+- Explicit mapping layer (source -> normalized -> target)
+- Validate required fields and types
+- Normalize common formats (dates, enums, currency, locales)
+- Handle nullability and partial payloads
+- Record rejected records with reasons (don’t silently drop)
+
+### 8) Error handling strategy
+Choose and document per error class:
+- **Skip with log** (non-critical record)
+- **Retry** (transient)
+- **Quarantine** (store failing payload for later)
+- **Fail the run** (systemic issue)
+Ensure the workflow reports a clear summary at the end.
+
+### 9) Observability & audit trail
+Minimum:
+- Run ID / correlation ID
+- Per-request logs: method, path (not full secrets), status, latency, attempt count
+- Counters: processed, created, updated, skipped, failed
+Prefer structured logs (JSON) if possible.
+
+### 10) Webhooks (if involved)
+- Verify signature (if provided)
+- Handle replay (idempotency for event IDs)
+- Respond quickly; process async if needed
+- Store raw event payloads (optional but recommended)
+
+### 11) Safety controls
+- Dry-run mode (no writes)
+- Limit scope (max records per run)
+- “Kill switch” config flag
+- Backups/rollback plan for destructive operations
+
+---
+
+## Output requirements (when producing a solution)
+Include:
+- Idempotency strategy (1–3 bullets)
+- Retry/backoff policy
+- Pagination/incremental sync approach (if relevant)
+- Error handling strategy + what gets logged/quarantined
+- Verification plan (tests or a safe sandbox run plan)

.agent/skills/superpowers-review/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: superpowers-review
+description: Reviews changes for correctness, edge cases, style, security, and maintainability with severity levels (Blocker/Major/Minor/Nit). Use before finalizing changes.
+---
+
+# Review Skill
+
+## When to use this skill
+- before delivering final code changes
+- after implementing a planned set of steps
+- before merging or shipping
+
+## Severity levels
+- **Blocker**: wrong behavior, security issue, data loss risk, broken tests/build
+- **Major**: likely bug, missing edge cases, poor reliability
+- **Minor**: style, clarity, small maintainability issues
+- **Nit**: optional polish
+
+## Checklist
+1. Correctness vs requirements
+2. Edge cases & error handling
+3. Tests (adequate coverage, meaningful assertions)
+4. Security (secrets, auth, injection, unsafe defaults)
+5. Performance (obvious hotspots, N+1, unnecessary work)
+6. Readability & maintainability
+7. Docs / comments updated if needed
+
+## Output format
+- Blockers
+- Majors
+- Minors
+- Nits
+- Overall summary + next actions

.agent/skills/superpowers-tdd/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: superpowers-tdd
+description: Applies tests-first discipline (red/green/refactor) and adds regression tests for bugs. Use when implementing features, fixing bugs, or refactoring.
+---
+
+# TDD Skill
+
+## When to use this skill
+- new features that can be unit tested
+- bug fixes (always add a regression test if practical)
+- refactors (protect behavior with tests first)
+
+## Rules
+- Prefer **red -> green -> refactor**.
+- If tests are hard, still add **verification**: minimal repro script, integration test, or clear manual steps.
+- Keep tests focused: one behavior per test where possible.
+- Name tests by behavior, not implementation details.
+
+## Process
+1. Define the behavior change (what should be true after).
+2. Write/adjust a test to capture it (make it fail first if possible).
+3. Implement the minimal change to pass.
+4. Refactor if needed (keep passing).
+5. Run the relevant test suite + any linters.
+
+## Output requirements
+When you change code, include:
+- what tests you added/changed
+- how to run them
+- what they prove

.agent/skills/superpowers-workflow/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: superpowers-workflow
+description: Enforces a disciplined workflow for coding, debugging, refactoring, and automation: brainstorm -> plan -> implement with verification (prefer TDD) -> review -> finish. Use for almost any non-trivial change.
+---
+
+# Superpowers Workflow
+
+This skill defines the default operating procedure for software and automation tasks.
+
+## When to use this skill
+Use whenever the user asks to:
+- build or modify code
+- debug an error or failing tests
+- refactor or improve quality
+- design an automation workflow (e.g., API integrations, ETL, pipelines)
+- add tests, reliability, or safety checks
+
+## Activation marker (required)
+Immediately after reading this skill (before any other output), run:
+
+python .agent/skills/superpowers-workflow/scripts/record_activation.py --skill superpowers-workflow
+
+
+## Default workflow (mandatory unless explicitly unnecessary)
+1. **Brainstorm (short)**: clarify goal, constraints, risks, and acceptance criteria.
+2. **Write a plan**: small steps (2–10 minutes each) with files + verification.
+3. **Implement**: make the smallest correct change; prefer tests-first when feasible.
+4. **Review pass**: correctness, edge cases, security, style, maintainability.
+5. **Finish**: run verification commands, summarize changes + next steps.
+
+## Decision tree: how much process is needed?
+- **Tiny change (1 file, obvious)**:
+  - Do a mini-brainstorm (3 bullets), then mini-plan (3–5 steps), then implement + verify.
+- **Non-trivial change**:
+  - Full brainstorm + plan before editing.
+- **High-risk change** (auth, money, prod data, security, migrations):
+  - Add explicit risk controls: rollback plan, dry-run, extra tests, logging, safe defaults.
+
+## Output rules (how you communicate)
+- Always state **assumptions** if anything is ambiguous.
+- Always include **verification** (commands, tests, or observable checks).
+- If you must ask questions, ask **at most 3**; then proceed with best assumptions.
+
+## Stop conditions
+Pause implementation and switch to planning if:
+- requirements conflict
+- critical unknowns block correctness
+- the change could cause data loss or security issues without safeguards

.agent/skills/superpowers-workflow/scripts/record_activation.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import argparse
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+def find_repo_root(start: Path) -> Path:
+    # Walk upwards until we find a marker that suggests repo root
+    for p in [start, *start.parents]:
+        if (p / ".agent").exists() or (p / ".git").exists() or (p / "pyproject.toml").exists():
+            return p
+    return start
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--skill", required=True)
+    parser.add_argument("--run-id", default="")
+    args = parser.parse_args()
+
+    repo_root = find_repo_root(Path.cwd())
+    log_path = repo_root / "e2e_demo" / "skill-activation.log"
+    log_path.parent.mkdir(parents=True, exist_ok=True)
+
+    ts = datetime.now(timezone.utc).isoformat()
+    line = f"{ts}\tskill={args.skill}\trun_id={args.run_id}\n"
+    log_path.write_text((log_path.read_text() if log_path.exists() else "") + line, encoding="utf-8")
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

.agent/skills/superpowers-workflow/scripts/spawn_subagent.py

@@ -0,0 +1,245 @@
+#!/usr/bin/env python3
+"""Spawn an isolated Gemini CLI subagent for focused task execution.
+
+This enables parallel execution by launching independent gemini instances
+with isolated context and specific skill instructions.
+"""
+
+import argparse
+import json
+import subprocess
+import sys
+import time
+import uuid
+from pathlib import Path
+from typing import Any
+
+
+def find_repo_root(start: Path) -> Path:
+    """Traverse upwards to find the repository root (containing .agent/)."""
+    curr = start.resolve()
+    for _ in range(10):
+        if (curr / ".agent").exists():
+            return curr
+        if curr.parent == curr:
+            break
+        curr = curr.parent
+    return Path.cwd()
+
+
+def load_skill_instructions(skill_path: Path) -> str:
+    """Load skill instructions from SKILL.md file."""
+    if not skill_path.exists():
+        return ""
+    return skill_path.read_text(encoding="utf-8")
+
+
+def spawn_subagent(
+    skill: str,
+    task: str,
+    repo_root: Path,
+    yolo: bool = True,
+    output_format: str = "text",
+) -> dict[str, Any]:
+    """
+    Spawn a subagent with isolated context.
+
+    Args:
+        skill: Skill name (e.g., 'tdd', 'debug', 'review')
+        task: Task description for the subagent
+        repo_root: Repository root path
+        yolo: Auto-approve all actions (default: True for parallel execution)
+        output_format: Output format ('text' or 'json')
+
+    Returns:
+        dict with keys: success, output, error, log_file, duration_s
+    """
+    # Generate unique subagent ID
+    subagent_id = uuid.uuid4().hex[:8]
+    timestamp = time.strftime("%Y%m%d-%H%M%S")
+
+    # Setup logging directory
+    log_dir = repo_root / "artifacts" / "superpowers" / "subagents"
+    log_dir.mkdir(parents=True, exist_ok=True)
+    log_file = log_dir / f"{skill}-{timestamp}-{subagent_id}.log"
+
+    # Load skill instructions
+    skill_file = repo_root / f".agent/skills/superpowers-{skill}/SKILL.md"
+    skill_instructions = load_skill_instructions(skill_file)
+
+    if not skill_instructions:
+        return {
+            "success": False,
+            "output": "",
+            "error": f"Skill not found: {skill_file}",
+            "log_file": str(log_file),
+            "duration_s": 0,
+        }
+
+    # Construct focused prompt
+    prompt = f"""You are a specialized subagent focused on: {skill}
+
+IMPORTANT: You have ISOLATED CONTEXT. Do not assume knowledge from other conversations.
+
+Task:
+{task}
+
+Skill Instructions:
+{skill_instructions}
+
+Requirements:
+1. Follow the skill instructions exactly
+2. Complete the task fully
+3. Output ONLY the final result at the end
+4. Do not include meta-commentary or thinking process in final output
+5. Write any artifacts to artifacts/superpowers/subagent-{subagent_id}/
+
+When complete, output:
+---SUBAGENT-RESULT-START---
+[Your final result here]
+---SUBAGENT-RESULT-END---
+"""
+
+    # Build command
+    cmd = ["gemini"]
+    if yolo:
+        cmd.append("--yolo")
+
+    # Execute subagent
+    start_time = time.time()
+
+    try:
+        with open(log_file, "w", encoding="utf-8") as log:
+            log.write("=== SUBAGENT EXECUTION LOG ===\n")
+            log.write(f"Skill: {skill}\n")
+            log.write(f"ID: {subagent_id}\n")
+            log.write(f"Timestamp: {timestamp}\n")
+            log.write(f"Task: {task}\n\n")
+            log.write("=== PROMPT ===\n")
+            log.write(prompt)
+            log.write("\n\n=== EXECUTION ===\n")
+            log.flush()
+
+            result = subprocess.run(
+                cmd,
+                input=prompt,
+                capture_output=True,
+                text=True,
+                cwd=repo_root,
+                timeout=600,  # 10 minute timeout
+                shell=True,  # Required on Windows for .ps1/.cmd scripts
+            )
+
+            duration_s = time.time() - start_time
+
+            log.write("\n=== STDOUT ===\n")
+            log.write(result.stdout)
+            log.write("\n=== STDERR ===\n")
+            log.write(result.stderr)
+            log.write(f"\n=== EXIT CODE: {result.returncode} ===\n")
+            log.write(f"=== DURATION: {duration_s:.2f}s ===\n")
+
+        # Extract final result from markers
+        output = result.stdout
+        if "---SUBAGENT-RESULT-START---" in output:
+            parts = output.split("---SUBAGENT-RESULT-START---", 1)
+            if len(parts) > 1:
+                result_part = parts[1].split("---SUBAGENT-RESULT-END---", 1)
+                output = result_part[0].strip()
+
+        return {
+            "success": result.returncode == 0,
+            "output": output,
+            "error": result.stderr if result.returncode != 0 else "",
+            "log_file": str(log_file),
+            "duration_s": duration_s,
+            "subagent_id": subagent_id,
+        }
+
+    except subprocess.TimeoutExpired:
+        duration_s = time.time() - start_time
+        return {
+            "success": False,
+            "output": "",
+            "error": f"Subagent timed out after {duration_s:.0f}s",
+            "log_file": str(log_file),
+            "duration_s": duration_s,
+            "subagent_id": subagent_id,
+        }
+    except Exception as e:
+        duration_s = time.time() - start_time
+        return {
+            "success": False,
+            "output": "",
+            "error": f"Subagent execution failed: {e}",
+            "log_file": str(log_file),
+            "duration_s": duration_s,
+            "subagent_id": subagent_id,
+        }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Spawn a Gemini CLI subagent for parallel execution"
+    )
+    parser.add_argument(
+        "--skill",
+        required=True,
+        help="Skill to use (tdd, debug, review, rest-automation, python-automation)",
+    )
+    parser.add_argument(
+        "--task",
+        required=True,
+        help="Task description for the subagent",
+    )
+    parser.add_argument(
+        "--no-yolo",
+        action="store_true",
+        help="Disable auto-approval (interactive mode)",
+    )
+    parser.add_argument(
+        "--output-format",
+        choices=["text", "json"],
+        default="text",
+        help="Output format",
+    )
+    args = parser.parse_args()
+
+    repo_root = find_repo_root(Path.cwd())
+
+    if args.output_format == "text":
+        print(f"🤖 Spawning subagent: {args.skill}")
+        print(f"📋 Task: {args.task[:80]}{'...' if len(args.task) > 80 else ''}")
+
+    result = spawn_subagent(
+        skill=args.skill,
+        task=args.task,
+        repo_root=repo_root,
+        yolo=not args.no_yolo,
+        output_format=args.output_format,
+    )
+
+    if args.output_format == "json":
+        print(json.dumps(result, indent=2))
+        return 0 if result["success"] else 1
+
+    # Text output
+    print(f"\n{'✅' if result['success'] else '❌'} Subagent completed in {result['duration_s']:.1f}s")
+    print(f"📝 Full log: {result['log_file']}")
+
+    if result["success"]:
+        print(f"\n{'='*60}")
+        print("RESULT:")
+        print(f"{'='*60}")
+        print(result["output"])
+        return 0
+    else:
+        print(f"\n{'='*60}")
+        print("ERROR:")
+        print(f"{'='*60}")
+        print(result["error"])
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

.agent/skills/superpowers-workflow/scripts/write_artifact.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+def find_repo_root(start: Path) -> Path:
+    for p in [start, *start.parents]:
+        if (p / ".agent").exists() or (p / ".git").exists():
+            return p
+    return start
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--path", required=True, help="Repo-relative path to write, e.g. artifacts/superpowers/brainstorm.md")
+    args = parser.parse_args()
+
+    repo_root = find_repo_root(Path.cwd())
+    out_path = (repo_root / args.path).resolve()
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+
+    content = sys.stdin.read()
+    out_path.write_text(content, encoding="utf-8")
+    print(str(out_path))
+    return 0
+
+if __name__ == "__main__":
+    raise SystemExit(main())

.agent/workflows/superpowers-brainstorm.md

@@ -0,0 +1,38 @@
+---
+description: Superpowers brainstorm. Produces goal/constraints/risks/options/recommendation/acceptance criteria.
+---
+
+# Superpowers Brainstorm
+
+## Task
+Brainstorm for this task (exactly as provided by the user):
+**{{input}}**
+
+If `{{input}}` is empty or missing, ask the user to restate the task in one sentence and STOP.
+
+## Output sections (use exactly)
+## Goal
+## Constraints
+## Known context
+## Risks
+## Options (2–4)
+## Recommendation
+## Acceptance criteria
+
+## Persist (mandatory)
+After generating the brainstorm content, you MUST write it to disk using this exact procedure:
+
+1) Output the brainstorm markdown content first (the sections above).
+2) Then immediately run:
+
+```bash
+python .agent/skills/superpowers-workflow/scripts/write_artifact.py --path artifacts/superpowers/brainstorm.md
+
+```
+
+Provide the brainstorm markdown as stdin to the command.
+
+After writing, confirm it exists by listing artifacts/superpowers/.
+
+If you cannot run the command, say so explicitly and instruct the user to copy/paste the brainstorm output into artifacts/superpowers/brainstorm.md.
+Do not implement changes in this workflow. Stop after persistence.

.agent/workflows/superpowers-debug.md

@@ -0,0 +1,33 @@
+---
+description: Systematic debugging workflow: reproduce, minimize, hypotheses, instrument, fix, prevent, verify.
+---
+
+# Superpowers Debug
+
+Read and apply the `superpowers-debug` skill.
+
+Use the required reporting format:
+- Symptom
+- Repro steps
+- Root cause
+- Fix
+- Regression protection
+- Verification
+
+## Persist (mandatory)
+After generating the debug content above, you MUST write it to disk:
+
+1) Copy the full debug markdown output.
+2) Run:
+
+```bash
+python .agent/skills/superpowers-workflow/scripts/write_artifact.py --path artifacts/superpowers/debug.md
+
+```
+
+Provide the debug markdown as stdin to the command.
+
+After writing, confirm it exists by listing artifacts/superpowers/.
+
+If you cannot run the command, say so explicitly and instruct the user to copy/paste the debug output into artifacts/superpowers/debug.md.
+Do not implement changes in this workflow. Stop after persistence.

.agent/workflows/superpowers-execute-plan-parallel.md

@@ -0,0 +1,213 @@
+---
+description: Execute an approved plan with parallel execution for independent steps. Spawns isolated subagents. Consolidates results.
+---
+
+# Superpowers Execute Plan (Parallel Mode)
+
+## Overview
+This workflow executes an approved plan by identifying independent steps and running them in parallel using isolated subagents.
+
+## When to use parallel mode
+- Plan has 2+ steps that don't depend on each other
+- Steps operate on different files or independent modules
+- You want faster execution (parallel > sequential)
+
+## When NOT to use parallel mode
+- Steps have dependencies (Step 2 needs Step 1's output)
+- All steps modify the same file
+- Plan has < 2 steps
+- You want simpler debugging (sequential is easier to debug)
+
+**If unsure, use `/superpowers-execute-plan` (sequential) instead.**
+
+---
+
+## Preconditions (do not skip)
+
+1. The user must have replied **APPROVED** to a written plan
+2. The approved plan must exist at: `artifacts/superpowers/plan.md`
+
+If `artifacts/superpowers/plan.md` does not exist:
+- Stop immediately
+- Tell the user to run `/superpowers-write-plan` first
+- Do not continue
+
+---
+
+## Load and analyze the plan
+
+1. Read `artifacts/superpowers/plan.md`
+2. Parse all plan steps
+3. Identify dependencies between steps:
+   - Does Step 2 modify files created/changed by Step 1?
+   - Does Step 2 need Step 1's verification to pass first?
+   - Do they modify the same files?
+4. Group steps into execution batches:
+   - **Batch 1**: All independent steps (no dependencies)
+   - **Batch 2**: Steps that depend on Batch 1 completing
+   - **Batch 3**: Steps that depend on Batch 2 completing
+   - etc.
+
+---
+
+## Execution strategy
+
+### For each batch:
+
+1. **Spawn subagents in parallel** for all steps in the batch:
+
+```bash
+# Example: Batch 1 has 3 independent steps
+python .agent/skills/superpowers-workflow/scripts/spawn_subagent.py \
+  --skill tdd \
+  --task "Step 1: Add retry logic to sync.py with exponential backoff" &
+
+python .agent/skills/superpowers-workflow/scripts/spawn_subagent.py \
+  --skill rest-automation \
+  --task "Step 2: Add pagination handling to fetch_items()" &
+
+python .agent/skills/superpowers-workflow/scripts/spawn_subagent.py \
+  --skill python-automation \
+  --task "Step 3: Update CLI args to support --max-retries flag" &
+
+# Wait for all to complete
+wait
+```
+
+2. **Collect results** from each subagent:
+   - Check log files in `artifacts/superpowers/subagents/`
+   - Extract final results from each
+   - Check success/failure status
+
+3. **Verify batch completion**:
+   - Run verification commands for all steps in the batch
+   - If ANY step fails:
+     - Stop execution
+     - Switch to `/superpowers-debug` for the failed step
+     - Do NOT continue to next batch
+
+4. **Append to execution log**:
+   - Write batch summary to `artifacts/superpowers/execution.md`:
+     ```markdown
+     ## Batch N (Parallel Execution)
+     - Step X: [SUCCESS/FAILED] - Files: [...] - Duration: Xs
+     - Step Y: [SUCCESS/FAILED] - Files: [...] - Duration: Ys
+
+     Verification:
+     - Step X: [command] -> [result]
+     - Step Y: [command] -> [result]
+     ```
+
+5. **Move to next batch** (if all steps passed)
+
+---
+
+## Skill selection for subagents
+
+Choose the appropriate skill for each step:
+
+| Step Type | Skill to Use |
+|-----------|-------------|
+| Add tests, TDD cycle | `tdd` |
+| Fix bugs, investigate failures | `debug` |
+| Code review, quality check | `review` |
+| REST API work | `rest-automation` |
+| Python tooling/scripts | `python-automation` |
+| General implementation | `tdd` (default) |
+
+---
+
+## Consolidation phase
+
+After all batches complete:
+
+1. **Integration verification**:
+   - Run full test suite (not just individual step tests)
+   - Verify all changes work together
+   - Check for conflicts between parallel changes
+
+2. **Conflict resolution**:
+   - If parallel steps modified related code:
+     - Review for integration issues
+     - Run combined tests
+     - Fix any conflicts
+
+3. **Final artifacts**:
+   - Update `artifacts/superpowers/execution.md` with:
+     - Total batches executed
+     - Total steps completed
+     - Total time saved vs sequential
+     - All verification results
+   - Write `artifacts/superpowers/finish.md` with:
+     - Summary of changes
+     - Integration test results
+     - Follow-up items (if any)
+
+---
+
+## Example: 5-step plan with 2 batches
+
+**Plan:**
+1. Add retry logic to sync.py (independent)
+2. Add pagination to API client (independent)
+3. Update CLI args (independent)
+4. Add integration test (depends on 1, 2, 3)
+5. Update docs (depends on 4 passing)
+
+**Execution:**
+
+**Batch 1 (parallel):**
+- Spawn 3 subagents for steps 1, 2, 3
+- Wait for all to complete (~5 min instead of ~15 min sequential)
+- Verify each step
+
+**Batch 2 (sequential):**
+- Step 4: Add integration test (needs 1+2+3 complete)
+- Verify test passes
+
+**Batch 3 (sequential):**
+- Step 5: Update docs (needs 4 complete)
+- Verify docs are accurate
+
+**Total time: ~10 min vs ~25 min sequential = 60% time savings**
+
+---
+
+## Troubleshooting
+
+### Subagent spawn fails
+- Check that `gemini` is in PATH (verify with: `gemini --version`)
+- Verify skill exists: `.agent/skills/superpowers-{skill}/SKILL.md`
+- Check subagent logs in `artifacts/superpowers/subagents/`
+
+### Steps conflict
+- Falls back to sequential execution for conflicting steps
+- Mark dependent steps explicitly in plan to avoid conflicts
+
+### Verification fails after parallel execution
+- Check integration - parallel steps may work individually but conflict
+- Run `/superpowers-debug` to investigate
+- Consider re-running in sequential mode: `/superpowers-execute-plan`
+
+---
+
+## Persist (mandatory)
+
+Write execution notes to disk:
+- Append batch summaries to: `artifacts/superpowers/execution.md`
+- Write final summary to: `artifacts/superpowers/finish.md`
+
+Ensure `artifacts/superpowers/` exists.
+Confirm files exist by listing `artifacts/superpowers/` when done.
+
+---
+
+## Finish
+
+After all steps complete:
+1. Run `/superpowers-review` (or inline review pass)
+2. Generate final summary with time savings metrics
+3. List all changed files
+4. Provide any manual validation steps
+
+Stop after completing the finish step.

.agent/workflows/superpowers-execute-plan.md

@@ -0,0 +1,84 @@
+---
+description: Executes an approved plan in small steps with verification after each step. Writes execution artifacts to disk. Stops on failures. Finishes with review + summary.
+---
+
+# Superpowers Execute Plan
+
+## Persist (mandatory)
+You must write execution artifacts to disk (not IDE-only documents):
+
+- Append execution notes to: `artifacts/superpowers/execution.md`
+- Write the final summary to: `artifacts/superpowers/finish.md`
+
+Requirements:
+1) Ensure the folder `artifacts/superpowers/` exists (create it if needed).
+2) After EACH completed plan step, append a note to `artifacts/superpowers/execution.md`.
+3) At the end, write the final summary to `artifacts/superpowers/finish.md`.
+4) After writing, confirm the files exist by listing `artifacts/superpowers/`.
+
+If you are unable to write these files directly, use `python .agent/skills/superpowers-workflow/scripts/write_artifact.py --path <target>` to persist the content.
+
+
+## Preconditions (do not skip)
+1) The user must have replied **APPROVED** to a written plan.
+2) The approved plan must exist on disk at:
+   - `artifacts/superpowers/plan.md`
+
+If `artifacts/superpowers/plan.md` does not exist:
+- Stop immediately.
+- Tell the user to run `/superpowers-write-plan` first.
+- Do not edit code.
+
+## Load the plan
+- Read `artifacts/superpowers/plan.md`.
+- Restate the plan briefly (1–2 lines) before making changes.
+
+## Check for parallel execution opportunity (optional)
+After loading the plan, analyze if steps can run in parallel:
+
+1. **Check for independent steps**: Do 2+ steps operate on different files with no dependencies?
+2. **If yes**: Suggest to the user:
+   - "I notice steps X, Y, Z are independent and could run in parallel."
+   - "Would you like to use `/superpowers-execute-plan-parallel` for faster execution?"
+   - "Or continue with sequential execution? (Reply: PARALLEL or SEQUENTIAL)"
+3. **If PARALLEL**: Stop and instruct user to run `/superpowers-execute-plan-parallel` instead.
+4. **If SEQUENTIAL or no independent steps**: Continue with sequential execution below.
+
+## Skills to apply as needed
+Read and apply these skills when relevant:
+- `superpowers-tdd` (preferred)
+- `superpowers-debug` (if issues occur)
+- `superpowers-review`
+- `superpowers-finish`
+- `superpowers-rest-automation` (if relevant)
+- `superpowers-python-automation` (if Python)
+
+## Execution rules (strict)
+1) Implement **ONE** plan step at a time.
+2) After each step:
+   - Run the step’s verification command(s) (or, if you cannot run them, provide exact commands and expected outcomes).
+   - Append a short note to `artifacts/superpowers/execution.md` containing:
+     - Step name
+     - Files changed
+     - What changed (1–3 bullets)
+     - Verification command(s)
+     - Result (pass/fail or “not run”)
+3) If verification fails:
+   - Stop.
+   - Switch to systematic debugging (use `superpowers-debug`).
+   - Do not continue executing further steps until fixed and verified.
+4) Keep changes minimal and scoped to the plan. If the plan is wrong or missing a step:
+   - Stop and update the plan (write the updated plan back to `artifacts/superpowers/plan.md`)
+   - Ask for approval again if the change is material.
+
+## Finish (required)
+At the end:
+1) Run a review pass (Blocker/Major/Minor/Nit).
+2) Write a final summary to `artifacts/superpowers/finish.md` including:
+   - Verification commands run + results
+   - Summary of changes
+   - Follow-ups (if any)
+   - Manual validation steps (if applicable)
+3) Confirm the artifacts exist by listing `artifacts/superpowers/`.
+
+Stop after completing the finish step.

.agent/workflows/superpowers-finish.md

@@ -0,0 +1,31 @@
+---
+description: Finalize work: verification, summary, follow-ups, manual validation steps.
+---
+
+# Superpowers Finish
+
+Read and apply the `superpowers-finish` skill.
+
+Output:
+## Verification (commands + results if possible)
+## Summary of changes
+## Follow-ups (if needed)
+## Manual validation steps (if applicable)
+
+## Persist (mandatory)
+After generating the finish content above, you MUST write it to disk:
+
+1) Copy the full finish markdown output.
+2) Run:
+
+```bash
+python .agent/skills/superpowers-workflow/scripts/write_artifact.py --path artifacts/superpowers/finish.md
+
+```
+
+Provide the finish markdown as stdin to the command.
+
+After writing, confirm it exists by listing artifacts/superpowers/.
+
+If you cannot run the command, say so explicitly and instruct the user to copy/paste the finish output into artifacts/superpowers/finish.md.
+Do not implement changes in this workflow. Stop after persistence.

.agent/workflows/superpowers-reload.md

@@ -0,0 +1,13 @@
+---
+description: Reloads Superpowers configuration by re-reading Rules, Workflows, and Skills from disk.
+---
+
+# Superpowers Reload
+
+Read these directories from disk and summarize what you loaded:
+- `.agent/rules/`
+- `.agent/workflows/`
+- `.agent/skills/` (list skill names + descriptions)
+
+Then confirm you will follow the latest versions in this session.
+Stop after confirming.

.agent/workflows/superpowers-review.md

@@ -0,0 +1,32 @@
+---
+description: Runs a Superpowers-style review pass with severity levels.
+---
+
+# Superpowers Review
+
+Read and apply the `superpowers-review` skill.
+
+Output:
+- Blockers
+- Majors
+- Minors
+- Nits
+- Summary + next actions
+
+## Persist (mandatory)
+After generating the review content above, you MUST write it to disk:
+
+1) Copy the full review markdown output.
+2) Run:
+
+```bash
+python .agent/skills/superpowers-workflow/scripts/write_artifact.py --path artifacts/superpowers/review.md
+
+```
+
+Provide the review markdown as stdin to the command.
+
+After writing, confirm it exists by listing artifacts/superpowers/.
+
+If you cannot run the command, say so explicitly and instruct the user to copy/paste the review output into artifacts/superpowers/review.md.
+Do not implement changes in this workflow. Stop after persistence.

.agent/workflows/superpowers-write-plan.md

@@ -0,0 +1,57 @@
+---
+description: Superpowers plan gate. Writes a small-step plan with files + verification. Must ask for approval before coding.
+---
+
+# Superpowers Write Plan (Gate)
+
+## Task
+Plan for this task (exactly as provided by the user):
+**{{input}}**
+
+If `{{input}}` is empty or missing, ask the user to restate the task in one sentence and STOP.
+
+## Rules
+- DO NOT edit code.
+- You may read files to understand context, but produce the plan and then stop.
+- Plan steps must be small (2–10 minutes each) and include verification commands.
+
+## Output format (use exactly)
+## Goal
+## Assumptions
+## Plan
+(Each step must include: Files, Change, Verify)
+## Risks & mitigations
+## Rollback plan
+
+## Persist (mandatory)
+Write the plan output to:
+- `artifacts/superpowers/plan.md`
+
+Create the folder if needed.
+After writing, confirm it exists by listing `artifacts/superpowers/`.
+
+## Approval
+Ask:
+**Approve this plan? Reply APPROVED if it looks good.**
+
+If the user replies APPROVED:
+- Do NOT implement yet.
+- Reply: **"Plan approved. Run `/superpowers-execute-plan` to begin implementation."**
+
+## Persist (mandatory)
+After generating the plan content above, you MUST write it to disk:
+
+1) Copy the full plan markdown output.
+2) Run:
+
+```bash
+python .agent/skills/superpowers-workflow/scripts/write_artifact.py --path artifacts/superpowers/plan.md
+
+```
+
+Provide the plan markdown as stdin to the command.
+
+After writing, confirm it exists by listing artifacts/superpowers/.
+
+If you cannot run the command, say so explicitly and instruct the user to copy/paste the plan output into artifacts/superpowers/plan.md.
+Do not implement changes in this workflow. Stop after persistence.

PROJECT_ARCHITECTURE.md

@@ -26,7 +26,7 @@ A unified system to maintain an inventory of "items" and their quantities, inclu
 - **PWA Deployment:** `next-pwa` (Service Workers + Manifest.json)
 - **HTTPS Proxy:** `caddy` or `local-ssl-proxy` (Port 8909)
 - **Servers:** Frontend (Port 8907), Backend (Port 8906)
-- **Configuration:** Centrally managed via root `config/` directory (includes `network_config.env`, `ldap_config.json`, `Caddyfile`).
+- **Configuration:** Centrally managed via root `inventory.env` (Network/CORS/API Keys) and `config/` directory (LDAP, Caddyfile).
 
 ## 3. Data Models & Entities
 - **Item:** Name, Category Group (Structured), Item Type (Specific), Quantity, Barcode, Part Number, Box Label (Association).
@@ -80,7 +80,9 @@ To ensure enterprise-grade protection, the following policies are enforced:
 - **Admin Only:** Critical operations such as `DELETE /items/`, user management, and DB settings are restricted via the `auth.get_current_admin` dependency.
 - **User Role:** Standard users are permitted to perform check-in/out and list inventory, but cannot delete catalog entries.
 
-### 7.2 Brute-Force Protection
+### 7.2 CORS & Origin Policy (v1.9.18)
+- **Automatic Discovery:** The system detects local LAN IP and automatically authorizes it.
+- **Generic Expansion:** Use `EXTRA_ALLOWED_ORIGINS` for Tailscale or VPN IPs. The system automatically expands each IP into a set of authorized Origins (http/8916, https/8918, https/8919).
 - **Rate Limiting:** Implemented via `slowapi`. The `login` endpoint is limited to **5 requests per minute** per IP to mitigate automated credential stuffing.
 
 ### 7.3 Data Privacy

README.md

@@ -12,8 +12,8 @@ This project supports three distinct operational modes:
 Ideal for local development on macOS/Linux.
 *   **Command:** `./start_server.sh`
 *   **Details:** Runs FastAPI (backend) and Next.js (frontend) in development mode. Uses `local-ssl-proxy` for HTTPS.
-*   **Backend:** http://localhost:8906
-*   **Frontend:** https://localhost:8909
+*   **Backend:** http://localhost:8916
+*   **Frontend:** https://localhost:8919
 
 ### 2. 🐳 Docker Mode (Recommended for Production)
 Isolated and portable container stack.
@@ -58,7 +58,8 @@ The application requires the following environment variables for production depl
 | Variable | Purpose | Example |
 |----------|---------|---------|
 | **JWT_SECRET_KEY** | JWT token signing key (REQUIRED for production) | `openssl rand -hex 32` |
-| **ALLOWED_ORIGINS** | CORS-allowed domain origins (comma-separated) | `https://inventory.example.com,https://api.example.com` |
+| **EXTRA_ALLOWED_ORIGINS** | Extra IPs or FQDNs for CORS (Tailscale, VPN, etc.) | `100.78.182.27,inventory.local` |
+| **ALLOWED_ORIGINS** | CORS-allowed domain origins (automatically includes LOCAL_IP) | `https://inventory.example.com` |
 | **DATA_DIR** | SQLite database location | `/app/data` |
 | **LOGS_DIR** | Application logs directory | `/app/logs` |
 

USER_GUIDE.md

@@ -44,10 +44,13 @@ You can now manage containers more efficiently with two specialized methods:
 
 ## 🏷️ Label Printing
 Administrators and users can generate physical labels for boxes to ensure 100% accurate scanning.
-1. Tap the **Package (Box)** icon in the header to open the **Box Inventory**.
-2. Find the box you want to label and tap **Print Label**.
-3. **Desktop:** Use the print dialog to send the label directly to a Dymo/Brother thermal printer.
-4. **Mobile:** Use **"Save for Mobile App"** to download a PNG image of the label, which you can then print using your Bluetooth printer's app (like NIIMBOT).
+## 🏷️ Label Printing
+Administrators and users can generate physical labels for boxes to ensure 100% accurate scanning.
+1. Tap the **Package (Box)** icon in the global header or the **Manage Boxes** card on the dashboard to open the **Box Inventory**.
+2. **Search:** Use the search bar inside the Box Manager to filter through your containers in real-time.
+3. Find the box you want to label and tap **Print Label**.
+4. **Desktop:** Use the print dialog to send the label directly to a Dymo/Brother thermal printer.
+5. **Mobile:** Use **"Save for Mobile App"** to download a PNG image of the label, which you can then print using your Bluetooth printer's app (like NIIMBOT).
 
 ---
 
@@ -102,8 +105,8 @@ Access application settings from the **Admin** panel.
 
 ### 🌐 Network & Configuration (NEW v1.8.0)
 The application now uses a centralized configuration folder in the project root:
-- **`config/`**: Contains all network settings (`network_config.env`), LDAP profiles (`ldap_config.json`), and security proxy rules (`Caddyfile`).
-- **Dynamic Port Mapping**: Changes to the server IP or ports in the configuration are automatically detected by both the frontend and backend after a restart.
+- **`inventory.env`**: The primary network configuration file. Centralizes `SERVER_IP`, ports, and `EXTRA_ALLOWED_ORIGINS`.
+- **Dynamic Port Mapping**: Changes to the server IP, ports, or allowed origins are automatically detected by both the frontend and backend after a restart.
 
 ---
 
@@ -146,5 +149,5 @@ For detailed technical documentation, see the [Project Architecture](../PROJECT_
 
 ---
 
-**Version:** v1.8.4
-**Last Updated:** 2026-04-13
+**Version:** v1.9.19
+**Last Updated:** 2026-04-14

backend/ai_vision.py

@@ -1,6 +1,5 @@
-import os
-from dotenv import load_dotenv
-from .ai import gemini, claude
+from . import models
+from .database import SessionLocal
 
 # Load environment variables from the directory where this file resides
 base_dir = os.path.dirname(os.path.abspath(__file__))
@@ -12,51 +11,74 @@ def extract_label_info(image_bytes: bytes, mode: str = "item"):
     Orchestrates extraction across multiple AI providers.
     Modes: 'item' (full technical extraction), 'box' (container discovery)
     """
-    if mode == "box":
-        prompt = """
-        Identify the CONTAINER or BOX name from this image.
-        Look for large, prominent, bold, or hand-written text that identifies a storage unit.
-        Ignore small technical details, quantities, or fine print.
+    db = SessionLocal()
+    try:
+        if mode == "box":
+            prompt = """
+            Identify the CONTAINER or BOX name from this image.
+            Look for large, prominent, bold, or hand-written text that identifies a storage unit.
+            Ignore small technical details, quantities, or fine print.
+            
+            Return ONLY a valid JSON object:
+            {
+              "box_label": "The identified container name",
+              "name": "Same as box_label",
+              "category": "Storage",
+              "description": "Brief description if useful",
+              "quantity": 1
+            }
+            """
+        else:
+            # Fetch custom prompt from DB
+            setting = db.query(models.SystemSetting).filter(models.SystemSetting.key == "ai_extraction_prompt").first()
+            if setting:
+                prompt = setting.value
+            else:
+                # Fallback to a sensible default if DB is not ready
+                prompt = "Extract technical specs. Return JSON with name, category, description, connector, size, color, part_number, ocr_text, quantity."
+
+        # 1. Try Gemini
+        result = gemini.extract(image_bytes, prompt)
         
-        Return ONLY a valid JSON object:
-        {
-          "box_label": "The identified container name",
-          "name": "Same as box_label",
-          "category": "Storage",
-          "specs": "Brief description if useful",
-          "quantity": 1
-        }
-        """
-    else:
-        prompt = """
-        Extract technical inventory information from this label image.
+        if result:
+            # Map user-defined prompt keys to model fields if needed
+            # User keys: Item, Type, Description, Category, Connector, Size, Color, PartNr, OCR
+            mapping = {
+                "Item": "name",
+                "Type": "type",
+                "Description": "description",
+                "Category": "category",
+                "Connector": "connector",
+                "Size": "size",
+                "Color": "color",
+                "PartNr": "part_number",
+                "OCR": "ocr_text"
+            }
+            
+            final_result = {}
+            for ai_key, model_key in mapping.items():
+                if ai_key in result:
+                    final_result[model_key] = result[ai_key]
+                elif model_key in result: # Already mapped or using model keys
+                    final_result[model_key] = result[model_key]
+            
+            # Ensure quantity and barcode are handled if returned or default
+            final_result["quantity"] = result.get("quantity", 1)
+            final_result["barcode"] = result.get("barcode", result.get("PartNr", result.get("part_number", "")))
+            
+            # Handle Box mode specifically
+            if mode == "box":
+                final_result["box_label"] = result.get("box_label", result.get("name", "Unknown Box"))
+                final_result["name"] = final_result["box_label"]
+
+            return final_result
+
+    finally:
+        db.close()
         
-        CRITICAL INSTRUCTIONS:
-        1. Look at the most prominent text (usually top 1-2 rows). This is the product NAME and MODEL.
-        2. Extract the PART NUMBER (P/N, Model No, Type). If no explicit Part Number is found, synthesize one from the most unique identifier in the header (e.g. 'OM4-MMF-DX').
-        3. Separate the COLOR (e.g. Turquoise, Yellow, Black).
-        4. Extract CATEGORY based on the item type (e.g. Patchcord, SFP, Connector).
-        5. Extract technical SPECS (e.g. '2.0mm', '10G', '850nm').
-        
-        Return ONLY a valid JSON object:
-        {
-          "name": "Full descriptive name from header",
-          "part_number": "Unique identifier for fast scanning",
-          "category": "Broad category",
-          "color": "Color if present",
-          "specs": "Brief tech specs list",
-          "barcode": "Barcode value if visible",
-          "quantity": 1
-        }
-        """
-    
-    # 1. Try Gemini
-    result = gemini.extract(image_bytes, prompt)
-    if result:
-        # Maintenance: Ensure fields are mapped if mode was box
-        if mode == "box" and "box_label" in result and "name" not in result:
-             result["name"] = result["box_label"]
-        return result
+    # 2. Try Claude (Fallback) - Note: Mapping logic would need to be replicated here if enabled
+    # For now, keeping it simple
+    return {"error": "AI extraction failed or no data returned. Check your API key and Prompt."}
         
     # 2. Try Claude (Fallback)
     result = claude.extract(image_bytes, prompt)

backend/db_manager.py

@@ -136,3 +136,36 @@ class DbManager:
         except Exception as e:
             logger.error(f"[DB] Restore failed: {str(e)}")
             raise Exception(f"Restore failed: {str(e)}")
+
+    @staticmethod
+    def export_db() -> str:
+        """Returns the path to the active database file for download."""
+        active_db_path = os.path.join(DATA_DIR, "inventory.db")
+        if not os.path.exists(active_db_path):
+            raise Exception("Database file not found")
+        return active_db_path
+
+    @staticmethod
+    def import_db(file_bytes: bytes, db: Session, user_id: int) -> bool:
+        """
+        Overwrites the active database with the provided file bytes.
+        Creates a safety rollback backup first.
+        """
+        active_db_path = os.path.join(DATA_DIR, "inventory.db")
+        
+        try:
+            # 1. Safety backup
+            DbManager.create_backup(db, label="import_rollback", user_id=user_id)
+            
+            # 2. Close pool connections
+            engine.dispose()
+            
+            # 3. Write new file
+            with open(active_db_path, "wb") as f:
+                f.write(file_bytes)
+                
+            logger.warning(f"[DB] IMPORT COMPLETED by user_id={user_id}")
+            return True
+        except Exception as e:
+            logger.error(f"[DB] Import failed: {str(e)}")
+            raise Exception(f"Import failed: {str(e)}")

backend/main.py

@@ -51,7 +51,23 @@ if server_ip and server_ip != "localhost":
         if ip_o not in ALLOWED_ORIGINS:
             ALLOWED_ORIGINS.append(ip_o)
 
-log.info(f"CORS allowed origins: {ALLOWED_ORIGINS}")
+# [NEW] Add Extra Allowed Origins (Tailscale, VPN, etc.)
+extra_origins_raw = os.environ.get("EXTRA_ALLOWED_ORIGINS", "")
+if extra_origins_raw:
+    for extra_ip in [o.strip() for o in extra_origins_raw.split(",") if o.strip()]:
+        # Generate standard combinations for this extra origin
+        ext_combos = [
+            f"http://{extra_ip}:{front_port}",
+            f"https://{extra_ip}:{front_ssl_port}",
+            f"https://{extra_ip}:{back_ssl_port}",
+        ]
+        for combo in ext_combos:
+            if combo not in ALLOWED_ORIGINS:
+                ALLOWED_ORIGINS.append(combo)
+
+log.info("🔒 [SECURITY] CORS configuration initialized.")
+for origin in ALLOWED_ORIGINS:
+    log.info(f"   -> Allowed: {origin}")
 
 # Add CORS middleware FIRST (before rate limiter)
 app.add_middleware(
@@ -78,6 +94,50 @@ def startup_event():
     scheduler.start()
     sync_scheduler_config()
 
+    # [NEW] Initialize default system settings
+    from .database import SessionLocal
+    db = SessionLocal()
+    try:
+        # Default AI Prompt from User Request
+        default_prompt = (
+            "identify and summarise the minimal necessary information for a quick description if item. "
+            "I need the following output - <field name> : the result from you.\n"
+            "For any field, do not add comments in parenthesis. \n\n"
+            "Item: in three words type of this item\n"
+            "Type: what type of item is, like \"spare parts\", \"consumables\", \"patch cords\"  etc.\n"
+            "Description: description (max 5 words)\n"
+            "Category: category, if any\n"
+            "Connector: connectors\n"
+            "Size: size or length\n"
+            "Color: color if useful\n"
+            "PartNr: part number if any\n"
+            "OCR: identification string for local OCR matching"
+        )
+        
+        # Wrap in JSON instructions for reliable parsing
+        final_prompt = f"IMAGE ANALYSIS INSTRUCTIONS:\n{default_prompt}\n\nIMPORTANT: Return ONLY a valid JSON object with the keys: Item, Type, Description, Category, Connector, Size, Color, PartNr, OCR."
+
+        existing = db.query(models.SystemSetting).filter(models.SystemSetting.key == "ai_extraction_prompt").first()
+        if not existing:
+            db.add(models.SystemSetting(key="ai_extraction_prompt", value=final_prompt))
+            db.commit()
+            log.info("Initialized default AI prompt.")
+
+        defaults = {
+            "backup_retention_count": "10",
+            "backup_schedule_hour": "3",
+            "backup_schedule_freq_days": "1"
+        }
+        for key, val in defaults.items():
+            if not db.query(models.SystemSetting).filter(models.SystemSetting.key == key).first():
+                db.add(models.SystemSetting(key=key, value=val))
+                log.info(f"Initialized default setting: {key}")
+        db.commit()
+    except Exception as e:
+        log.error(f"Failed to initialize settings: {e}")
+    finally:
+        db.close()
+
 @app.get("/")
 def read_root():
     return {"message": "Inventory API is running"}

backend/models.py

@@ -23,6 +23,12 @@ class Category(Base):
 
     items = relationship("Item", back_populates="category_rel")
 
+class Color(Base):
+    __tablename__ = "colors"
+
+    id = Column(Integer, primary_key=True, index=True)
+    name = Column(String, unique=True, index=True)
+
 class Item(Base):
     __tablename__ = "items"
 
@@ -36,6 +42,10 @@ class Item(Base):
     category_rel = relationship("Category", back_populates="items")
     part_number = Column(String, index=True, nullable=True)
     color = Column(String, index=True, nullable=True)
+    description = Column(String, nullable=True)
+    connector = Column(String, nullable=True)
+    size = Column(String, nullable=True)
+    ocr_text = Column(Text, nullable=True)
     specs = Column(Text, nullable=True)
     quantity = Column(Float, default=0.0)
     min_quantity = Column(Float, default=1.0)

backend/routers/admin_db.py

@@ -5,6 +5,8 @@ from .. import models, schemas, auth
 from ..database import get_db
 from ..db_manager import DbManager
 from ..scheduler import sync_scheduler_config
+from fastapi.responses import FileResponse
+from fastapi import UploadFile, File
 
 router = APIRouter(
     prefix="/admin/db",
@@ -103,3 +105,63 @@ def update_db_settings(
     # Re-trigger scheduler sync
     sync_scheduler_config()
     return settings
+
+@router.get("/export")
+def export_database(
+    current_admin: auth.TokenData = Depends(auth.get_current_admin)
+):
+    """Download the current database file."""
+    try:
+        path = DbManager.export_db()
+        return FileResponse(
+            path, 
+            media_type="application/x-sqlite3", 
+            filename="inventory_export.db"
+        )
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+@router.post("/import")
+async def import_database(
+    file: UploadFile = File(...),
+    db: Session = Depends(get_db),
+    current_admin: auth.TokenData = Depends(auth.get_current_admin)
+):
+    """Upload and replace the current database. DANGEROUS."""
+    contents = await file.read()
+    try:
+        DbManager.import_db(contents, db, user_id=current_admin.sub)
+        return {"status": "success", "message": "Database successfully imported and replaced."}
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+@router.get("/settings/prompt")
+def get_ai_prompt(
+    db: Session = Depends(get_db),
+    current_admin: auth.TokenData = Depends(auth.get_current_admin)
+):
+    """Get the current AI extraction prompt."""
+    setting = db.query(models.SystemSetting).filter(models.SystemSetting.key == "ai_extraction_prompt").first()
+    if not setting:
+        return {"value": ""}
+    return {"value": setting.value}
+
+@router.post("/settings/prompt")
+def update_ai_prompt(
+    payload: dict,
+    db: Session = Depends(get_db),
+    current_admin: auth.TokenData = Depends(auth.get_current_admin)
+):
+    """Update the AI extraction prompt."""
+    value = payload.get("value")
+    if value is None:
+        raise HTTPException(status_code=400, detail="Value required")
+    
+    existing = db.query(models.SystemSetting).filter(models.SystemSetting.key == "ai_extraction_prompt").first()
+    if existing:
+        existing.value = value
+    else:
+        db.add(models.SystemSetting(key="ai_extraction_prompt", value=value))
+    
+    db.commit()
+    return {"status": "success"}

backend/routers/items.py

@@ -97,10 +97,18 @@ def create_item(
     current_user: auth.TokenData = Depends(auth.get_current_user)
 ):
     """[C-01] Create item — only for authenticated users. [M-02] user_id from token."""
-    # Check if barcode exists
-    db_item = db.query(models.Item).filter(models.Item.barcode == item.barcode).first()
-    if db_item:
-        raise HTTPException(status_code=400, detail="Barcode already registered")
+    # [AUTO-PERSIST] Create Category/Color if not exists
+    if item.category:
+        cat = db.query(models.Category).filter(models.Category.name == item.category).first()
+        if not cat:
+            db.add(models.Category(name=item.category))
+            db.commit()
+            
+    if item.color:
+        col = db.query(models.Color).filter(models.Color.name == item.color).first()
+        if not col:
+            db.add(models.Color(name=item.color))
+            db.commit()
 
     db_item = models.Item(**item.model_dump())
     db.add(db_item)
@@ -148,6 +156,19 @@ def update_item(
     if not db_item:
         raise HTTPException(status_code=404, detail="Item not found")
 
+    # [AUTO-PERSIST] Create Category/Color if not exists
+    if item.category:
+        cat = db.query(models.Category).filter(models.Category.name == item.category).first()
+        if not cat:
+            db.add(models.Category(name=item.category))
+            db.commit()
+            
+    if item.color:
+        col = db.query(models.Color).filter(models.Color.name == item.color).first()
+        if not col:
+            db.add(models.Color(name=item.color))
+            db.commit()
+
     update_data = item.model_dump(exclude_unset=True)
     for key, value in update_data.items():
         setattr(db_item, key, value)

backend/routers/users.py

@@ -20,13 +20,19 @@ limiter = Limiter(key_func=get_remote_address)
 pwd_context = CryptContext(schemes=["pbkdf2_sha256"], deprecated="auto")
 
 def get_ldap_config():
-    # Read from root /config directory
-    root_dir = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
-    config_dir = os.path.join(root_dir, "config")
-    config_path = os.path.join(config_dir, "ldap_config.json")
+    # Priority 1: Check in DATA_DIR (for Docker production)
+    config_path = os.path.join(database.DATA_DIR, "config", "ldap_config.json")
     if os.path.exists(config_path):
         with open(config_path, "r") as f:
             return json.load(f)
+            
+    # Priority 2: Fallback to source-relative config (for local dev)
+    root_dir = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+    source_config_path = os.path.join(root_dir, "config", "ldap_config.json")
+    if os.path.exists(source_config_path):
+        with open(source_config_path, "r") as f:
+            return json.load(f)
+            
     return {"ldap_enabled": False}
 
 def authenticate_ldap(username, password):
@@ -73,6 +79,11 @@ def authenticate_ldap(username, password):
             return None
 
         real_user_dn = conn.entries[0].entry_dn
+        user_groups = []
+        if hasattr(conn.entries[0], 'memberOf'):
+            user_groups = [str(g).lower() for g in conn.entries[0].memberOf.values]
+            log.debug(f"LDAP: Found memberOf groups on user: {user_groups}")
+        
         log.debug(f"LDAP: Canonical DN found: {real_user_dn}")
         
         # Check roles based on group membership
@@ -87,27 +98,39 @@ def authenticate_ldap(username, password):
         groups_dn = config.get("groups_dn", "ou=groups")
         
         # Iterate through mappings to find the highest role
-        # Priority: admin > user
         potential_roles = []
         
         for mapping in role_mappings:
             group_name = mapping["group"]
             target_role = mapping["role"]
             
-            # Construct group DN if it's just a common name, else use as is
+            # Construct group DN if it's just a common name
             if "=" not in group_name:
                 full_group_dn = f"cn={group_name},{groups_dn},{base_dn}"
             else:
                 full_group_dn = group_name
-                
+            
+            full_group_dn_lower = full_group_dn.lower()
+            
             log.debug(f"LDAP: Checking membership in group: {full_group_dn}")
-            conn.search(full_group_dn, '(objectClass=*)', attributes=['member'])
+            
+            # Method 1: Check memberOf if available (AD/LLDAP)
+            if full_group_dn_lower in user_groups:
+                log.debug(f"LDAP: Match found via memberOf for {target_role}")
+                potential_roles.append(target_role)
+                continue
 
+            # Method 2: Search group's member attribute (Standard LDAP)
+            conn.search(full_group_dn, '(objectClass=*)', attributes=['member', 'uniqueMember'])
             if conn.entries:
-                members = conn.entries[0].member.values
-                if real_user_dn in members or user_dn in members or \
-                   any(m.lower().replace(" ", "") == real_user_dn.lower().replace(" ", "") for m in members):
-                    log.debug(f"LDAP: User is in group {group_name}, assigning role: {target_role}")
+                members = []
+                if hasattr(conn.entries[0], 'member'):
+                    members = [str(m).lower() for m in conn.entries[0].member.values]
+                elif hasattr(conn.entries[0], 'uniqueMember'):
+                    members = [str(m).lower() for m in conn.entries[0].uniqueMember.values]
+                
+                if real_user_dn.lower() in members or user_dn.lower() in members:
+                    log.debug(f"LDAP: Match found via group search for {target_role}")
                     potential_roles.append(target_role)
         
         if "admin" in potential_roles:
@@ -166,8 +189,9 @@ def get_users(db: Session = Depends(get_db)):
     users = db.query(models.User).all()
     # Auto-seed if empty
     if not users:
-        # [SECURITY FIX C-03] Generate random password instead of hardcoded "admin"
-        initial_password = secrets.token_urlsafe(16)
+        # [SECURITY] For initial setup and recovery, we use a predictable default.
+        # User MUST change this immediately in Settings.
+        initial_password = "Admin123!"
         new_user = models.User(
             username="Admin",
             role="admin",
@@ -177,7 +201,7 @@ def get_users(db: Session = Depends(get_db)):
         db.add(new_user)
         db.commit()
         db.refresh(new_user)
-        log.warning(f"[SECURITY] Admin initial seeded. Temporary password: {initial_password} — CHANGE IMMEDIATELY!")
+        log.warning(f"[SECURITY] Admin initial seeded. Credentials: Admin / {initial_password} — CHANGE IMMEDIATELY!")
         return [new_user]
     return users
 

backend/schemas.py

@@ -51,6 +51,19 @@ class Category(CategoryBase):
     class Config:
         from_attributes = True
 
+# --- Colors ---
+class ColorBase(BaseModel):
+    name: str
+
+class ColorCreate(ColorBase):
+    pass
+
+class Color(ColorBase):
+    id: int
+
+    class Config:
+        from_attributes = True
+
 # --- Items ---
 class ItemBase(BaseModel):
     name: str
@@ -60,6 +73,10 @@ class ItemBase(BaseModel):
     barcode: str
     part_number: Optional[str] = None
     color: Optional[str] = None
+    description: Optional[str] = None
+    connector: Optional[str] = None
+    size: Optional[str] = None
+    ocr_text: Optional[str] = None
     specs: Optional[str] = None
     quantity: float = 0.0
     min_quantity: float = 1.0

backend/scripts/init_settings.py

@@ -0,0 +1,51 @@
+import sys
+import os
+
+# Add parent directory to path
+sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from database import SessionLocal, engine
+import models
+
+def init_settings():
+    db = SessionLocal()
+    try:
+        # Default AI Prompt from User Request
+        default_prompt = """identify and summarise the minimal necessary information for a quick description if item. I need the following output - <field name> : the result from you.
+For any field, do not add comments in parenthesis. 
+
+Item: in three words type of this item
+Type: what type of item is, like "spare parts", "consumables", "patch cords"  etc.
+Description: description (max 5 words)
+Category: category, if any
+Connector: connectors
+Size: size or length
+Color: color if useful
+PartNr: part number if any
+OCR: identification string for local OCR matching"""
+
+        # We will wrap this in a instruction to return JSON for easier parsing while keeping the user's content
+        final_prompt = f"IMAGE ANALYSIS INSTRUCTIONS:\n{default_prompt}\n\nIMPORTANT: Return ONLY a valid JSON object with the keys: Item, Type, Description, Category, Connector, Size, Color, PartNr, OCR."
+
+        existing = db.query(models.SystemSetting).filter(models.SystemSetting.key == "ai_extraction_prompt").first()
+        if not existing:
+            db.add(models.SystemSetting(key="ai_extraction_prompt", value=final_prompt))
+            print("Added default AI prompt setting.")
+        
+        # Add default backup settings if missing
+        defaults = {
+            "backup_retention_count": "10",
+            "backup_schedule_hour": "3",
+            "backup_schedule_freq_days": "1"
+        }
+        for key, val in defaults.items():
+            if not db.query(models.SystemSetting).filter(models.SystemSetting.key == key).first():
+                db.add(models.SystemSetting(key=key, value=val))
+                print(f"Added default setting: {key}")
+
+        db.commit()
+    finally:
+        db.close()
+
+if __name__ == "__main__":
+    init_settings()

backend/scripts/migrate_v4_v5.py

@@ -0,0 +1,49 @@
+import sqlite3
+import os
+from ..database import db_path
+from ..logger import log
+
+def migrate():
+    """
+    Migration script to upgrade the items table from schema v4 to v5.
+    Adds columns: description, connector, size, ocr_text.
+    """
+    log.info(f"🚀 Starting database migration on {db_path}...")
+    
+    if not os.path.exists(db_path):
+        log.error(f"❌ Database file not found at {db_path}")
+        return
+
+    conn = sqlite3.connect(db_path)
+    cursor = conn.cursor()
+    
+    try:
+        # Check existing columns
+        cursor.execute("PRAGMA table_info(items)")
+        columns = [row[1] for row in cursor.fetchall()]
+        
+        new_columns = [
+            ("description", "VARCHAR"),
+            ("connector", "VARCHAR"),
+            ("size", "VARCHAR"),
+            ("ocr_text", "TEXT")
+        ]
+        
+        for col_name, col_type in new_columns:
+            if col_name not in columns:
+                log.info(f"➕ Adding column '{col_name}' to 'items' table...")
+                cursor.execute(f"ALTER TABLE items ADD COLUMN {col_name} {col_type}")
+            else:
+                log.info(f"✔️ Column '{col_name}' already exists.")
+        
+        conn.commit()
+        log.info("✅ Migration completed successfully.")
+        
+    except Exception as e:
+        log.error(f"❌ Migration failed: {e}")
+        conn.rollback()
+    finally:
+        conn.close()
+
+if __name__ == "__main__":
+    migrate()

backend/scripts/reset_admin.py

@@ -0,0 +1,41 @@
+import os
+import sys
+from sqlalchemy.orm import Session
+from passlib.context import CryptContext
+from ..database import SessionLocal
+from .. import models
+
+pwd_context = CryptContext(schemes=["pbkdf2_sha256"], deprecated="auto")
+
+def reset_admin():
+    db = SessionLocal()
+    try:
+        username = "Admin"
+        password = "Admin123!"
+        hashed_password = pwd_context.hash(password)
+        
+        user = db.query(models.User).filter(models.User.username == username).first()
+        if user:
+            user.hashed_password = hashed_password
+            user.role = "admin"
+            print(f"✅ User '{username}' found. Password has been reset to: {password}")
+        else:
+            new_user = models.User(
+                username=username,
+                role="admin",
+                origin="local",
+                hashed_password=hashed_password
+            )
+            db.add(new_user)
+            print(f"✅ User '{username}' not found. Created new admin with password: {password}")
+            
+        db.commit()
+        print("💾 Changes saved to database.")
+    except Exception as e:
+        print(f"❌ Error resetting admin: {e}")
+        db.rollback()
+    finally:
+        db.close()
+
+if __name__ == "__main__":
+    reset_admin()

config/Caddyfile

@@ -1,12 +1,41 @@
-# TFM aInventory - Caddy Self-Signed Internal Proxy
-# This replaces the need for `local-ssl-proxy` in Node.
+# TFM aInventory - Caddy Patched IP Configuration
+# Version 1.9.17 - The Dynamic Shield (Production Polish)
 {
-:{$FRONTEND_SSL_PORT} {
-    tls internal
-    reverse_proxy frontend:3000
+    admin off
+    # Global TLS options for self-signed certificates
+    local_certs
+    skip_install_trust
+    
+    # Configure on-demand TLS for private network IPs
+    on_demand_tls {
+        # Pointing to the backend root which returns 200 OK
+        # This allows Caddy to generate internal certs for any IP/domain.
+        ask http://backend:8000/
+    }
+}
 
 # Dynamic SSL Proxy (Matches ANY IP or hostname)
-:{$BACKEND_SSL_PORT} {
-    tls internal
+https:// {
+    tls internal {
+        on_demand
+    }
+    
+    reverse_proxy frontend:3000
+    
+    header {
+        Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
+        X-XSS-Protection "1; mode=block"
+        X-Content-Type-Options "nosniff"
+        X-Frame-Options "SAMEORIGIN"
+        Referrer-Policy "strict-origin-when-cross-origin"
+    }
+}
+
+# Specific port listener for backend (8918 -> 444)
+https://:444 {
+    tls internal {
+        on_demand
+    }
+    reverse_proxy backend:8000
 }
 }

config/backend.env.example

@@ -5,21 +5,21 @@
 # ============================================================
 
 # --- AI API Keys ---
-# Google Gemini API Key (required for AI label OCR onboarding)
+# Google Gemini API Key (Required for AI label OCR onboarding)
+# You can also set this in the root 'inventory.env' for Docker convenience.
 GEMINI_API_KEY=your_gemini_api_key_here
 
 # --- Security ---
 # JWT secret key — generate a strong random value for production:
 #   python3 -c "import secrets; print(secrets.token_urlsafe(64))"
-# If not set, an ephemeral key is generated per-run (tokens invalidated on restart).
 JWT_SECRET_KEY=change-me-generate-a-secure-random-value
 
-# --- CORS ---
-# Comma-separated list of allowed frontend origins
-# Example for LAN deployment:
-#   ALLOWED_ORIGINS=http://192.168.84.113:8907,https://192.168.84.113:8909
-ALLOWED_ORIGINS=http://localhost:8907,https://localhost:8909
+# --- CORS & External Access ---
+# The system automatically allows localhost and the local LAN IP.
+# Use EXTRA_ALLOWED_ORIGINS for Tailscale, VPNs, or FQDNs.
+# Example: EXTRA_ALLOWED_ORIGINS=100.78.182.27,inventory.my-domain.com
+EXTRA_ALLOWED_ORIGINS=
 
-# --- Data Paths (overridden by start_server.sh / docker-compose) ---
-# DATA_DIR=/absolute/path/to/data
-# LOGS_DIR=/absolute/path/to/logs
+# --- Data Paths (usually managed by startup scripts) ---
+# DATA_DIR=/app/data
+# LOGS_DIR=/app/logs

config/ldap_config.json.example

@@ -1,19 +1,17 @@
 {
-  "_comment": "Copy this file to ldap_config.json and fill in real values. NEVER commit ldap_config.json to Git.",
   "ldap_enabled": false,
-  "server_uri": "ldap://YOUR_LDAP_SERVER_IP:389",
-  "base_dn": "dc=yourdomain,dc=com",
-  "user_template": "cn={username},ou=people,dc=yourdomain,dc=com",
-  "groups_dn": "ou=groups",
+  "server_uri": "ldap://192.168.1.100:389",
   "use_tls": false,
   "ignore_cert": false,
+  "base_dn": "dc=example,dc=com",
+  "user_template": "uid={username},ou=users,dc=example,dc=com",
   "role_mappings": [
     {
-      "group": "inventory_admins",
+      "group": "cn=inventory_admins,ou=groups,dc=example,dc=com",
       "role": "admin"
     },
     {
-      "group": "inventory_users",
+      "group": "cn=inventory_users,ou=groups,dc=example,dc=com",
       "role": "user"
     }
   ]

config/proxy/Dockerfile

@@ -0,0 +1,8 @@
+FROM caddy:2-alpine
+
+# Install nss-tools to allow Caddy to manage its internal trust store (fixes certutil warning)
+# Install ca-certificates to ensure Caddy can trust external sites if needed
+RUN apk add --no-cache nss-tools ca-certificates
+
+# Expose the internal proxy ports
+EXPOSE 80 443 444

deploy.sh

@@ -0,0 +1,83 @@
+#!/bin/bash
+# =============================================================================
+# TFM aInventory - Bulletproof Deployment Script (v1.9.12)
+# =============================================================================
+
+set -e
+
+# Load environment variables (from root inventory.env)
+if [ -f inventory.env ]; then
+    export $(grep -v '^#' inventory.env | xargs)
+    echo "✅ Loaded configuration from inventory.env"
+else
+    echo "⚠️  inventory.env not found. Using default values."
+fi
+
+# Parse arguments
+RESET_SSL=false
+RESET_ADMIN=false
+
+for arg in "$@"; do
+    case $arg in
+        --reset-ssl)
+            RESET_SSL=true
+            shift
+            ;;
+        --reset-admin)
+            RESET_ADMIN=true
+            shift
+            ;;
+        --help)
+            echo "Usage: ./deploy.sh [options]"
+            echo "Options:"
+            echo "  --reset-ssl    Clear Caddy storage and reset certificates (Aggressive)"
+            echo "  --reset-admin  Force reset Admin password to 'Admin123!'"
+            echo "  --help         Show this help message"
+            exit 0
+            ;;
+    esac
+done
+
+if [ "$RESET_SSL" = true ]; then
+    echo "🧹 Aggressive SSL Reset in progress..."
+    docker compose down
+    # Clear internal docker volumes
+    docker volume rm -f inventory_caddy_data 2>/dev/null || true
+    docker volume rm -f inventory_caddy_config 2>/dev/null || true
+    # Clear persistent host volumes if they exist
+    rm -rf ./data/caddy_data/* 2>/dev/null || true
+    rm -rf ./data/caddy_config/* 2>/dev/null || true
+    echo "✅ SSL storage completely cleared."
+fi
+
+echo "🚀 Starting TFM aInventory Services..."
+# Use --build to ensure the custom Caddy image is built
+docker compose --env-file inventory.env up -d --build --remove-orphans
+
+if [ "$RESET_ADMIN" = true ]; then
+    echo "🔐 Resetting Admin credentials..."
+    # Wait for container to be ready
+    sleep 3
+    docker compose exec backend python3 -m backend.scripts.reset_admin
+fi
+
+echo ""
+echo "🔍 Verifying port mapping..."
+docker compose ps --format "table {{.Name}}\t{{.Status}}\t{{.Ports}}"
+
+echo ""
+echo "🚀 DIAGNOSTIC LOGS (Proxy Status):"
+docker compose logs proxy --tail 20
+
+echo ""
+echo "✅ Deployment complete (v1.9.12)."
+echo "   ------------------------------------------------------------"
+echo "   ACCESS COORDINATES:"
+echo "   1. SECURE: https://${SERVER_IP:-localhost}:${FRONTEND_SSL_PORT:-8919}"
+echo "   2. DIRECT: http://${SERVER_IP:-localhost}:${FRONTEND_PORT:-8917}"
+echo "   ------------------------------------------------------------"
+echo "   CREDENTIALS (if first run or reset):"
+echo "   User: Admin"
+echo "   Pass: Admin123!"
+echo "   ------------------------------------------------------------"
+echo ""

dev_docs/SESSION_HISTORY.md

@@ -123,3 +123,81 @@ Obiectiv: audit de securitate complet înainte de producție.
 1. Implement Phase 5: Gemini AI Vision Integration for New Item Onboarding.
 2. Build the "History / Audit" view in the frontend.
 3. Add "Trash/Discard" logic to the frontend UI.
+# CURRENT AI WORKING SESSION — HANDOVER
+
+**Active AI:** Gemini (Antigravity)
+**Last Updated:** 2026-04-12
+**Current Version:** v1.6.0 (BoxMaster)
+**Branch:** dev
+
+---
+
+## STATUS: 🟢 STABLE — ADVANCED BOX MANAGEMENT & AI MODES COMPLETE (v1.6.0)
+
+**CRITICAL FOR NEXT AI:** The "Box/Container Management" feature is **FINISHED**. Do NOT attempt to re-implement or look for a plan. The core logic is already in `frontend/app/page.tsx` (`onOCRMatch` and `BoxManager`), `backend/models.py`, and `frontend/lib/labels.ts`.
+
+---
+
+## WHAT WAS DONE THIS SESSION
+
+### 1. Box Management Architecture (Backend)
+- **Database Schema** — Added `box_label` column to the `items` table.
+- **Audit Integrity** — Updated `AuditLog` snapshots to capture `box_label` at the time of each transaction, ensuring immutable historical traceability even if items are moved.
+- **API Support** — Exposed `box_label` in Pydantic schemas and item routers.
+
+### 2. Intelligent Scanner Routing (Frontend)
+- **Box Match Priority** — Rewrote the scanner's `onOCRMatch` logic to prioritize box labels.
+- **Multi-Item Support** — Developed a "Box Contents" interstitial modal that handles containers with multiple distinct item types.
+- **Token Matching** — Implemented a local fuzzy token-matching engine for generic box text recognition without AI costs.
+
+### 3. Dependency-Free Label System
+- **Native Generation** — Built a zero-dependency SVG engine for Code 128 Barcodes and QR Codes (`lib/labels.ts`).
+- **Box Manager Dashboard** — Added a dedicated UI to view all existing boxes and trigger label generation.
+- **Hybrid Printing** — Implemented CSS `@media print` for professional desktop printers and "Save as PNG" rasterization for portable Bluetooth printers on mobile.
+
+### 4. UI/UX: Targeted Field Scanning
+- **Camera Capture** — Added a dedicated scan button in Edit modals that redirects OCR results directly to the "Box Label" field without performing general item matches.
+
+### 5. Multi-Mode AI Discovery
+- **Contextual Prompts** — Implemented a dual-mode toggle (Item/Box) in the AI Onboarding screen.
+- **Box Extraction** — Created a specialized prompt for Gemini 2.0 Flash to extract container names while filtering out technical noise from product labels.
+
+### 6. Operational Rigor: Step 0 Rule
+- **Mandatory Documentation** — Updated `AI_RULES.md` to force documentation verification before any `save-version` (git commit) operation.
+- **Master Branch Sync** — Confirmed `scripts/save_version.py` logic to keep `master` branch in sync with the latest releases automatically.
+
+---
+
+## WHAT THE NEXT AI MUST DO
+
+1. **Database Encryption** — Consider implementing SQLite encryption at rest (SQLCipher) if requested.
+2. **Persistent JWT** — If requested, move the `JWT_SECRET_KEY` to a `.env` file for session persistence across server restarts.
+3. **Advanced Filtering** — Extend the Box Manager to allow bulk movements between boxes.
+3. **LDAP Probe** — The "Test Connection" button may show "Partial Success" (handshake rejected) due to anonymous bind restrictions; login itself works fine.
+4. **Monitoring** — If the rate limiter triggers too frequently for legitimate users, adjust the `slowapi` limit in `backend/routers/users.py`.
+
+---
+
+## SYSTEM STATE
+
+**Active database:** `<project_root>/data/inventory.db`
+**LDAP config:** `config/ldap_config.json`
+**Network config:** `config/network_config.env`
+**Proxy config:** `config/Caddyfile`
+**Production Bundle:** `aInventory-PROD-v1.8.0.zip` (ConfigSync Final)
+
+> [!IMPORTANT]
+> **Git Access Fix**: The `xcode-select` breakage is bypassed by using the direct binary path: `/Library/Developer/CommandLineTools/usr/bin/git` (stored in `.git_path`). **DO NOT change this path.** Operations now work correctly via this direct link.
+
+**How to start:**
+```bash
+./start_server.sh
+```
+- Frontend: `https://192.168.84.113:8909`
+- Backend: `https://192.168.84.113:8908`
+
+**Environment variables set by start_server.sh:**
+- `ALLOWED_ORIGINS` — auto-detected
+- `DATA_DIR` — absolute path
+- `JWT_SECRET_KEY` — ephemeral (regenerates on restart)
+\n---\n

dev_docs/SESSION_STATE.md

@@ -1,55 +1,41 @@
 # CURRENT AI WORKING SESSION — HANDOVER
 
 **Active AI:** Gemini (Antigravity)
-**Last Updated:** 2026-04-12
-**Current Version:** v1.6.0 (BoxMaster)
+**Last Updated:** 2026-04-13
+**Current Version:** v1.9.18 (CORS Sync)
 **Branch:** dev
 
 ---
 
-## STATUS: 🟢 STABLE — ADVANCED BOX MANAGEMENT & AI MODES COMPLETE (v1.6.0)
+## STATUS: 🟢 STABLE — GENERIC CORS & CONFIG CENTRALIZATION COMPLETE
 
-**CRITICAL FOR NEXT AI:** The "Box/Container Management" feature is **FINISHED**. Do NOT attempt to re-implement or look for a plan. The core logic is already in `frontend/app/page.tsx` (`onOCRMatch` and `BoxManager`), `backend/models.py`, and `frontend/lib/labels.ts`.
+**CRITICAL FOR NEXT AI:** The CORS system has been upgraded to support `EXTRA_ALLOWED_ORIGINS` in `inventory.env`. The backend automatically expands these into full URLs (http/https across all ports).
 
 ---
 
 ## WHAT WAS DONE THIS SESSION
 
-### 1. Box Management Architecture (Backend)
-- **Database Schema** — Added `box_label` column to the `items` table.
-- **Audit Integrity** — Updated `AuditLog` snapshots to capture `box_label` at the time of each transaction, ensuring immutable historical traceability even if items are moved.
-- **API Support** — Exposed `box_label` in Pydantic schemas and item routers.
+### 1. Generic CORS (External Access)
+- **Variable**: Introduced `EXTRA_ALLOWED_ORIGINS` in `inventory.env`.
+- **Backend Expansion**: Updated `backend/main.py` to automatically generate allowed origins (plain/SSL) for any IP or FQDN provided in this comma-separated list.
+- **Tailscale Ready**: Pre-configured with `100.78.182.27` as requested by the user.
 
-### 2. Intelligent Scanner Routing (Frontend)
-- **Box Match Priority** — Rewrote the scanner's `onOCRMatch` logic to prioritize box labels.
-- **Multi-Item Support** — Developed a "Box Contents" interstitial modal that handles containers with multiple distinct item types.
-- **Token Matching** — Implemented a local fuzzy token-matching engine for generic box text recognition without AI costs.
+### 2. Configuration Centralization
+- **inventory.env Updates**: Added placeholders for `GEMINI_API_KEY` and security tokens to encourage usage of a single configuration file for both local and Docker deployments.
+- **Port Consistency**: Cleaned up `config/backend.env.example` to reflect the actual ports used (8916-8919).
 
-### 3. Dependency-Free Label System
-- **Native Generation** — Built a zero-dependency SVG engine for Code 128 Barcodes and QR Codes (`lib/labels.ts`).
-- **Box Manager Dashboard** — Added a dedicated UI to view all existing boxes and trigger label generation.
-- **Hybrid Printing** — Implemented CSS `@media print` for professional desktop printers and "Save as PNG" rasterization for portable Bluetooth printers on mobile.
+### 3. Startup & Discovery
+- **Dynamic Access Banner**: Enhanced `start_server.sh` to detect `EXTRA_ALLOWED_ORIGINS` and display the corresponding Tailscale/VPN URLs at startup.
 
-### 4. UI/UX: Targeted Field Scanning
-- **Camera Capture** — Added a dedicated scan button in Edit modals that redirects OCR results directly to the "Box Label" field without performing general item matches.
-
-### 5. Multi-Mode AI Discovery
-- **Contextual Prompts** — Implemented a dual-mode toggle (Item/Box) in the AI Onboarding screen.
-- **Box Extraction** — Created a specialized prompt for Gemini 2.0 Flash to extract container names while filtering out technical noise from product labels.
-
-### 6. Operational Rigor: Step 0 Rule
-- **Mandatory Documentation** — Updated `AI_RULES.md` to force documentation verification before any `save-version` (git commit) operation.
-- **Master Branch Sync** — Confirmed `scripts/save_version.py` logic to keep `master` branch in sync with the latest releases automatically.
+### 4. Verification
+- **Test Script**: Verified the CORS expansion logic with `scratch/verify_cors.py` (deleted after use).
 
 ---
 
 ## WHAT THE NEXT AI MUST DO
 
-1. **Database Encryption** — Consider implementing SQLite encryption at rest (SQLCipher) if requested.
-2. **Persistent JWT** — If requested, move the `JWT_SECRET_KEY` to a `.env` file for session persistence across server restarts.
-3. **Advanced Filtering** — Extend the Box Manager to allow bulk movements between boxes.
-3. **LDAP Probe** — The "Test Connection" button may show "Partial Success" (handshake rejected) due to anonymous bind restrictions; login itself works fine.
-4. **Monitoring** — If the rate limiter triggers too frequently for legitimate users, adjust the `slowapi` limit in `backend/routers/users.py`.
+1. **Docker Sync**: If the user experiences issues with the API key in Docker, suggest rebuilding the image or ensuring `inventory.env` is correctly mounted.
+2. **Reverse Proxy**: If a more complex FQDN setup is needed, consider updating `config/Caddyfile` to handle wildcard subdomains if `EXTRA_ALLOWED_ORIGINS` list becomes too long.
 
 ---
 
@@ -57,21 +43,16 @@
 
 **Active database:** `<project_root>/data/inventory.db`
 **LDAP config:** `config/ldap_config.json`
-**Network config:** `config/network_config.env`
+**Network config:** `inventory.env` (Now the Primary SSOT for networking)
 **Proxy config:** `config/Caddyfile`
-**Production Bundle:** `aInventory-PROD-v1.8.0.zip` (ConfigSync Final)
-
-> [!IMPORTANT]
-> **Git Access Fix**: The `xcode-select` breakage is bypassed by using the direct binary path: `/Library/Developer/CommandLineTools/usr/bin/git` (stored in `.git_path`). **DO NOT change this path.** Operations now work correctly via this direct link.
 
 **How to start:**
 ```bash
 ./start_server.sh
 ```
-- Frontend: `https://192.168.84.113:8909`
-- Backend: `https://192.168.84.113:8908`
+- Local URL: `https://localhost:8919`
+- LAN URL: `https://192.168.84.113:8919`
+- Tailscale URL: `https://100.78.182.27:8919` (Now allowed in CORS)
 
-**Environment variables set by start_server.sh:**
-- `ALLOWED_ORIGINS` — auto-detected
-- `DATA_DIR` — absolute path
-- `JWT_SECRET_KEY` — ephemeral (regenerates on restart)
+---
+✓ Done.

docker-compose.yml

@@ -8,10 +8,11 @@ services:
     ports:
       - ${BACKEND_PORT:-8000}:8000
     env_file:
-      - .env
+      - inventory.env
     volumes:
       - ./data:/app/data
       - ./logs:/app/logs
+      - ./config:/app/config
       - ./scripts:/app/scripts:ro
     environment:
       - DATA_DIR=/app/data
@@ -28,7 +29,7 @@ services:
     ports:
       - ${FRONTEND_PORT:-3000}:3000
     env_file:
-      - .env
+      - inventory.env
     volumes:
       - ./logs:/app/logs
     # Write Next.js logs to both stdout (docker logs) and file (mapped volume)
@@ -36,14 +37,16 @@ services:
     restart: unless-stopped
 
   proxy:
-    image: caddy:alpine
+    build:
+      context: .
+      dockerfile: config/proxy/Dockerfile
     networks:
       - inventory_net
     ports:
-      - ${BACKEND_SSL_PORT:-3002}:${BACKEND_SSL_PORT:-3002}
-      - ${FRONTEND_SSL_PORT:-3003}:${FRONTEND_SSL_PORT:-3003}
+      - ${BACKEND_SSL_PORT:-8918}:444
+      - ${FRONTEND_SSL_PORT:-8919}:443
     env_file:
-      - .env
+      - inventory.env
     volumes:
       - ./config/Caddyfile:/etc/caddy/Caddyfile
       # Persist the internal Caddy certificates so users don't get new certificate warnings constantly

export_prod.sh

@@ -29,7 +29,8 @@ cp install_service.sh "$PROD_DIR/"
 cp inventory.service.template "$PROD_DIR/"
 cp USER_GUIDE.md "$PROD_DIR/"
 cp README.md "$PROD_DIR/INSTALLATION_GUIDE.md"
-cp .env "$PROD_DIR/"
+cp inventory.env "$PROD_DIR/"
+cp deploy.sh "$PROD_DIR/"
 cp .git_path "$PROD_DIR/" 2>/dev/null || true
 cp frontend/VERSION.json "$PROD_DIR/"
 cp frontend/VERSION.json "$PROD_DIR/frontend/"

frontend/VERSION.json

@@ -1 +1,6 @@
-{"version": "1.9.4", "last_build": "2026-04-13-2115", "codename": "SingleSource", "commit": "30be9678"}
+{
+  "version": "1.9.19",
+  "last_build": "2026-04-13-2343",
+  "codename": "MobilePolish",
+  "commit": "1fff658d"
+}

frontend/app/admin/page.tsx

@@ -13,21 +13,12 @@ import {
   Plus, 
   AlertTriangle, 
   LogOut, 
-  Database,
-  History,
-  Lock,
-  Edit2,
-  X,
-  Server,
-  Globe,
-  Wifi,
-  WifiOff,
-  Layers,
-  ChevronDown,
-  Clock,
   HardDrive,
   Download,
-  RotateCcw
+  RotateCcw,
+  FileText,
+  Upload,
+  Brain
 } from 'lucide-react';
 import { toast } from 'react-hot-toast';
 import { cn } from '@/lib/utils';
@@ -61,6 +52,11 @@ export default function AdminPage() {
   const [dbStats, setDbStats] = useState({ backup_count: 0, total_size_bytes: 0 });
   const [dbSettings, setDbSettings] = useState({ retention_count: 10, schedule_hour: 3, schedule_freq_days: 1 });
   const [isBackingUp, setIsBackingUp] = useState(false);
+  const [isImporting, setIsImporting] = useState(false);
+
+  // AI Prompt State
+  const [aiPrompt, setAiPrompt] = useState("");
+  const [isSavingPrompt, setIsSavingPrompt] = useState(false);
 
   useEffect(() => {
     loadData();
@@ -83,6 +79,9 @@ export default function AdminPage() {
       setBackups(b);
       setDbStats(s);
       setDbSettings(st);
+      
+      const p = await inventoryApi.getAiPrompt();
+      setAiPrompt(p.value);
     } catch (err: any) {
       console.error(err);
       toast.error("Failed to load admin data");
@@ -213,6 +212,60 @@ export default function AdminPage() {
     }
   };
 
+  const handleUpdatePrompt = async () => {
+    setIsSavingPrompt(true);
+    try {
+      await inventoryApi.updateAiPrompt(aiPrompt);
+      toast.success("AI Extraction Prompt updated");
+    } catch (err: any) {
+      toast.error("Failed to update AI prompt");
+    } finally {
+      setIsSavingPrompt(false);
+    }
+  };
+
+  const handleExportDb = async () => {
+    try {
+      const blob = await inventoryApi.exportDb();
+      const url = window.URL.createObjectURL(blob);
+      const a = document.createElement('a');
+      a.href = url;
+      a.download = `inventory_backup_${new Date().toISOString().split('T')[0]}.db`;
+      document.body.appendChild(a);
+      a.click();
+      window.URL.revokeObjectURL(url);
+      toast.success("Database exported successfully");
+    } catch (err: any) {
+      toast.error("Export failed");
+    }
+  };
+
+  const handleImportDb = async (e: React.ChangeEvent<HTMLInputElement>) => {
+    const file = e.target.files?.[0];
+    if (!file) return;
+    
+    if (!confirm("DANGEROUS: You are about to REPLACE the entire database with this file. All current data will be lost. Proceed?")) {
+      e.target.value = '';
+      return;
+    }
+
+    setIsImporting(true);
+    const formData = new FormData();
+    formData.append('file', file);
+
+    const loadingToast = toast.loading("Importing database...");
+    try {
+      await inventoryApi.importDb(formData);
+      toast.success("Database imported! Reloading system...", { id: loadingToast });
+      setTimeout(() => window.location.reload(), 2000);
+    } catch (err: any) {
+      toast.error("Import failed: " + (err.response?.data?.detail || err.message), { id: loadingToast });
+    } finally {
+      setIsImporting(false);
+      e.target.value = '';
+    }
+  };
+
   const handleUpdateLdap = async () => {
     setLoading(true);
     try {
@@ -565,6 +618,48 @@ export default function AdminPage() {
           </div>
         </section>
 
+        {/* AI Configuration Section */}
+        <section className="glass-card p-6 md:p-8 rounded-[2.5rem] md:rounded-[3rem] space-y-8">
+           <div className="flex flex-col sm:flex-row sm:items-center justify-between gap-6 px-2">
+            <div className="flex items-center gap-4">
+              <div className="p-3 bg-purple-500/10 rounded-2xl text-purple-500 border border-purple-500/20">
+                <Brain size={24} />
+              </div>
+              <div>
+                <h2 className="text-xl font-black text-white">AI Vision Intelligence</h2>
+                <p className="text-xs text-slate-500 font-bold mt-1">Configure extraction prompts and heuristic models</p>
+              </div>
+            </div>
+            <button 
+              onClick={handleUpdatePrompt}
+              disabled={isSavingPrompt}
+              className="bg-purple-600 hover:bg-purple-500 text-white font-black text-xs px-6 py-3 rounded-xl shadow-xl shadow-purple-500/20 transition-all active:scale-95 disabled:opacity-50 flex items-center gap-2"
+            >
+              {isSavingPrompt ? <div className="w-3 h-3 border-2 border-white border-t-transparent animate-spin rounded-full" /> : <Edit2 size={14} />}
+              Save AI Prompt
+            </button>
+          </div>
+
+          <div className="space-y-4">
+             <div className="flex items-center gap-2 px-1">
+                <FileText size={14} className="text-purple-400" />
+                <label className="text-xs font-black text-slate-300">Global Extraction Prompt</label>
+             </div>
+             <textarea 
+               value={aiPrompt}
+               onChange={(e) => setAiPrompt(e.target.value)}
+               placeholder="Enter the AI system prompt for label extraction..."
+               className="w-full bg-slate-950/80 border border-slate-800 rounded-3xl p-6 text-sm text-slate-300 font-mono leading-relaxed min-h-[300px] outline-none focus:border-purple-500/30 transition-all custom-scrollbar"
+             />
+             <div className="bg-purple-500/5 border border-purple-500/10 p-5 rounded-2xl">
+                <p className="text-[10px] text-slate-500 leading-relaxed font-bold italic">
+                  Tip: Use specific instructions like "Return ONLY valid JSON" to ensure consistent results. 
+                  Reference fields: <span className="text-purple-400/80">Item, Type, Description, Category, Connector, Size, Color, PartNr, OCR</span>.
+                </p>
+             </div>
+          </div>
+        </section>
+
         {/* Category Management Section */}
         <section className="glass-card p-6 md:p-8 rounded-[2.5rem] md:rounded-[3rem] space-y-8">
           <div className="flex items-center justify-between px-2">
@@ -674,18 +769,38 @@ export default function AdminPage() {
                 <p className="text-xs text-slate-500 font-bold mt-1">Snapshot management and disaster recovery tools</p>
               </div>
             </div>
-            <button 
-              onClick={handleCreateBackup}
-              disabled={isBackingUp}
-              className="group flex items-center justify-center gap-2 bg-amber-500/10 hover:bg-amber-500 text-amber-500 hover:text-white font-black text-xs px-6 py-3 rounded-xl transition-all border border-amber-500/20 active:scale-95 disabled:opacity-50"
-            >
-              {isBackingUp ? (
-                <div className="w-3 h-3 border-2 border-current border-t-transparent animate-spin rounded-full" />
-              ) : (
-                <Download size={14} className="group-hover:-translate-y-0.5 transition-transform" />
-              )}
-              Create Manual Backup
-            </button>
+            <div className="flex items-center gap-3">
+               <button 
+                 onClick={handleExportDb}
+                 className="flex items-center justify-center gap-2 bg-slate-800 hover:bg-slate-700 text-slate-300 font-black text-xs px-5 py-3 rounded-xl transition-all border border-slate-700 active:scale-95"
+                 title="Download current database as .db file"
+               >
+                 <Download size={14} /> Export
+               </button>
+               <label className="flex items-center justify-center gap-2 bg-slate-800 hover:bg-rose-900/20 text-slate-300 hover:text-rose-400 font-black text-xs px-5 py-3 rounded-xl transition-all border border-slate-700 hover:border-rose-500/30 cursor-pointer active:scale-95">
+                 <Upload size={14} /> Import
+                 <input 
+                   type="file" 
+                   accept=".db,.sqlite,.sqlite3" 
+                   className="hidden" 
+                   onChange={handleImportDb}
+                   disabled={isImporting}
+                 />
+               </label>
+               <div className="w-px h-8 bg-slate-800 mx-2" />
+               <button 
+                 onClick={handleCreateBackup}
+                 disabled={isBackingUp}
+                 className="group flex items-center justify-center gap-2 bg-amber-500/10 hover:bg-amber-500 text-amber-500 hover:text-white font-black text-xs px-6 py-3 rounded-xl transition-all border border-amber-500/20 active:scale-95 disabled:opacity-50"
+               >
+                 {isBackingUp ? (
+                   <div className="w-3 h-3 border-2 border-current border-t-transparent animate-spin rounded-full" />
+                 ) : (
+                   <Download size={14} className="group-hover:-translate-y-0.5 transition-transform" />
+                 )}
+                 Snapshot
+               </button>
+            </div>
           </div>
 
           <div className="grid lg:grid-cols-3 gap-6">

frontend/app/login/page.tsx

@@ -88,37 +88,56 @@ export default function LoginPage() {
             <User size={32} />
           </div>
           <h2 className="text-2xl font-black text-white tracking-tight">Identity Check</h2>
-          <p className="text-slate-500 text-sm">Select operator profile or use enterprise login</p>
+          <p className="text-slate-500 text-sm">Select operator profile or use direct login</p>
         </div>
         
         <div className="grid gap-3">
           {!selectedUserForLogin && !isEnterprise ? (
             <>
-              {users.map(user => (
-                <button
-                  key={user.id}
-                  onClick={() => handleSelectUser(user)}
-                  className="bg-slate-800/50 hover:bg-slate-800 border border-slate-800 hover:border-primary/40 p-4 rounded-2xl text-left transition-all group flex items-center justify-between"
-                >
-                  <div className="flex items-center gap-3">
-                    <div className="w-8 h-8 rounded-full bg-slate-900 border border-slate-700 flex items-center justify-center text-slate-500 group-hover:text-primary transition-colors">
-                      {user.role === 'admin' ? <Shield size={14} /> : <User size={14} />}
-                    </div>
-                    <div>
-                      <p className="text-white font-black text-sm">{user.username}</p>
-                      <p className="text-xs text-slate-500 font-bold mt-1">{user.role}</p>
-                    </div>
-                  </div>
-                  <ChevronRight size={16} className="text-slate-600 group-hover:text-primary transition-colors" />
-                </button>
-              ))}
-              <div className="pt-2">
+              {users.length > 0 ? (
+                <>
+                  {users.map(user => (
+                    <button
+                      key={user.id}
+                      onClick={() => handleSelectUser(user)}
+                      className="bg-slate-800/50 hover:bg-slate-800 border border-slate-800 hover:border-primary/40 p-4 rounded-2xl text-left transition-all group flex items-center justify-between"
+                    >
+                      <div className="flex items-center gap-3">
+                        <div className="w-8 h-8 rounded-full bg-slate-900 border border-slate-700 flex items-center justify-center text-slate-500 group-hover:text-primary transition-colors">
+                          {user.role === 'admin' ? <Shield size={14} /> : <User size={14} />}
+                        </div>
+                        <div>
+                          <p className="text-white font-black text-sm">{user.username}</p>
+                          <p className="text-xs text-slate-500 font-bold mt-1">{user.role}</p>
+                        </div>
+                      </div>
+                      <ChevronRight size={16} className="text-slate-600 group-hover:text-primary transition-colors" />
+                    </button>
+                  ))}
+                </>
+              ) : (
+                <div className="text-center p-4 text-slate-500 text-xs font-bold animate-pulse">
+                   Connectivity issues? Use manual login below.
+                </div>
+              )}
+              
+              <div className="pt-2 grid grid-cols-2 gap-3">
                 <button
                   onClick={() => setIsEnterprise(true)}
-                  className="w-full flex items-center justify-center gap-2 py-4 rounded-2xl border border-dashed border-slate-700 text-slate-500 hover:text-primary hover:border-primary/40 transition-all font-bold text-xs"
+                  className="flex items-center justify-center gap-2 py-4 rounded-2xl border border-dashed border-slate-700 text-slate-500 hover:text-white hover:border-slate-500 transition-all font-bold text-[10px]"
                 >
-                  <Shield size={14} />
-                  Enterprise Login
+                  <Lock size={12} />
+                  Enterprise
+                </button>
+                <button
+                  onClick={() => {
+                    setSelectedUserForLogin({ username: '' });
+                    // We use an empty username object to trigger the manual input view
+                  }}
+                  className="flex items-center justify-center gap-2 py-4 rounded-2xl border border-primary/20 bg-primary/5 text-primary hover:bg-primary/10 transition-all font-bold text-[10px]"
+                >
+                  <User size={12} />
+                  Manual Login
                 </button>
               </div>
             </>
@@ -180,10 +199,26 @@ export default function LoginPage() {
                 </button>
                 <div>
                   <p className="text-sm font-bold text-slate-500">Logging in as</p>
-                  <p className="text-white font-black">{selectedUserForLogin.username}</p>
+                  <p className="text-white font-black">{selectedUserForLogin.username || "Manual Input"}</p>
                 </div>
               </div>
               
+              {!selectedUserForLogin.username && (
+                <div className="space-y-2">
+                  <label className="text-xs font-black text-slate-500 px-1">Username</label>
+                  <div className="relative">
+                    <User className="absolute left-4 top-1/2 -translate-y-1/2 text-slate-500" size={16} />
+                    <input 
+                      type="text"
+                      autoFocus
+                      onChange={(e) => setSelectedUserForLogin({...selectedUserForLogin, username: e.target.value})}
+                      className="w-full bg-slate-800/50 border border-slate-800 focus:border-primary rounded-2xl py-4 pl-12 pr-4 text-white focus:outline-none transition-all placeholder:text-slate-700 font-mono"
+                      placeholder="Admin"
+                    />
+                  </div>
+                </div>
+              )}
+              
               <div className="space-y-2">
                 <label className="text-xs font-black text-slate-500 px-1">Password</label>
                 <div className="relative">
@@ -209,9 +244,10 @@ export default function LoginPage() {
           )}
         </div>
         
-        {users.length === 0 && (
-          <div className="text-center p-8 text-slate-500 animate-pulse">
-            Initializing users...
+        {/* Progress bar hint */}
+        {users.length === 0 && !selectedUserForLogin && !isEnterprise && (
+          <div className="w-full bg-slate-800 h-1 rounded-full overflow-hidden">
+            <div className="bg-primary h-full animate-progress-fast shadow-[0_0_8px_rgba(var(--primary-rgb),0.5)]"></div>
           </div>
         )}
       </div>

frontend/app/page.tsx

@@ -82,6 +82,7 @@ export default function Home() {
   const [currentUser, setCurrentUser] = useState<any | null>(null);
   const [categories, setCategories] = useState<any[]>([]);
   const [fieldScanning, setFieldScanning] = useState<{ active: boolean, field: string } | null>(null);
+  const [boxSearchQuery, setBoxSearchQuery] = useState('');
 
   useEffect(() => {
     if (!localStorage.getItem('inventory_token')) {
@@ -291,6 +292,10 @@ export default function Home() {
       const sn = (item.serial_number || '').toUpperCase();
       const name = item.name.toUpperCase();
       const category = item.category.toUpperCase();
+      const ocrKey = (item.ocr_text || '').toUpperCase().replace(/[^A-Z0-9\s/+-]/g, ' ');
+
+      // Priority 0: Exact OCR Key match (Heuristic provided by AI)
+      if (ocrKey && cleanText.includes(ocrKey)) score += 1000;
 
       // Priority 1: Serial Number (Absolute match)
       if (sn && cleanText.includes(sn)) score += 500;
@@ -418,10 +423,13 @@ export default function Home() {
     return (
       item.name.toLowerCase().includes(query) ||
       item.category.toLowerCase().includes(query) ||
-      (item.specs?.toLowerCase().includes(query) ?? false) ||
+      (item.description?.toLowerCase().includes(query) ?? false) ||
+      (item.connector?.toLowerCase().includes(query) ?? false) ||
+      (item.size?.toLowerCase().includes(query) ?? false) ||
       (item.part_number?.toLowerCase().includes(query) ?? false) ||
       (item.color?.toLowerCase().includes(query) ?? false) ||
-      (item.box_label?.toLowerCase().includes(query) ?? false)
+      (item.box_label?.toLowerCase().includes(query) ?? false) ||
+      (item.ocr_text?.toLowerCase().includes(query) ?? false)
     );
   });
 
@@ -471,60 +479,60 @@ export default function Home() {
             </div>
           </div>
 
-          <div className="flex flex-wrap items-center justify-between sm:justify-end gap-3 sm:gap-6 bg-slate-900/40 sm:bg-transparent p-3 sm:p-0 rounded-2xl border border-slate-800/50 sm:border-none">
-            <div className="flex flex-wrap items-center gap-4">
+          <div className="flex flex-wrap items-center justify-between sm:justify-end gap-3 sm:gap-6 bg-slate-900/40 sm:bg-transparent px-4 py-2 sm:p-0 rounded-2xl border border-slate-800/50 sm:border-none">
+            <div className="flex flex-wrap items-center gap-4 sm:gap-6">
               {isScannerReady && (
-                <div className="flex items-center gap-1.5">
-                  <div className="w-1 h-1 rounded-full bg-green-500 shadow-[0_0_5px_rgba(34,197,94,0.5)]" />
-                  <span className="text-xs font-black text-green-500/80 whitespace-nowrap">
-                    Offline Scan: OK
+                <div className="flex items-center gap-2">
+                  <div className="w-1.5 h-1.5 rounded-full bg-green-500 shadow-[0_0_8px_rgba(34,197,94,0.6)]" />
+                  <span className="text-[10px] sm:text-xs font-black text-green-500/90 whitespace-nowrap">
+                    Scanner: OK
                   </span>
                 </div>
               )}
-              <div className="flex items-center gap-1.5">
-                <div className={`w-1 h-1 rounded-full ${isOnline ? 'bg-green-500 animate-pulse shadow-[0_0_5px_rgba(34,197,94,0.5)]' : 'bg-rose-500 shadow-[0_0_5px_rgba(244,63,94,0.5)]'}`} />
-                <span className={`text-xs font-black whitespace-nowrap ${isOnline ? 'text-green-500/80' : 'text-rose-500/80'}`}>
-                  Server Sync: {isOnline ? 'OK' : 'No'}
+              <div className="flex items-center gap-2">
+                <div className={`w-1.5 h-1.5 rounded-full ${isOnline ? 'bg-green-500 animate-pulse shadow-[0_0_8px_rgba(34,197,94,0.6)]' : 'bg-rose-500 shadow-[0_0_8px_rgba(244,63,94,0.6)]'}`} />
+                <span className={`text-[10px] sm:text-xs font-black whitespace-nowrap ${isOnline ? 'text-green-500/90' : 'text-rose-500/90'}`}>
+                  Sync: {isOnline ? 'Active' : 'Offline'}
                 </span>
               </div>
             </div>
             <div className="flex items-center gap-2">
-            <button 
-              onClick={() => setShowBoxManager(true)}
-              className="p-3 bg-slate-900 border border-slate-800 text-slate-400 rounded-xl hover:text-primary transition-colors hover:border-primary/30"
-              title="Box Manager"
-            >
-              <Package size={20} />
-            </button>
-            <button 
-              onClick={handleSync} 
-              disabled={syncing}
-              className="p-3 bg-slate-900 border border-slate-800 text-slate-400 rounded-xl hover:text-white transition-colors disabled:opacity-50"
-            >
-              <RefreshCw size={20} className={syncing ? "animate-spin text-primary" : ""} />
-            </button>
-          </div>
+              <button 
+                onClick={() => setShowBoxManager(true)}
+                className="p-2.5 bg-slate-900/80 border border-slate-800 text-slate-400 rounded-xl hover:text-primary transition-all active:scale-95"
+                title="Box Manager"
+              >
+                <Package size={18} />
+              </button>
+              <button 
+                onClick={handleSync} 
+                disabled={syncing}
+                className="p-2.5 bg-slate-900/80 border border-slate-800 text-slate-400 rounded-xl hover:text-white transition-all active:scale-95 disabled:opacity-50"
+              >
+                <RefreshCw size={18} className={syncing ? "animate-spin text-primary" : ""} />
+              </button>
+            </div>
           </div>
         </header>
 
         <div className="w-full px-1 space-y-6">
           {/* Mode Switcher */}
-          <div className="flex p-1 bg-slate-900/80 backdrop-blur-md rounded-2xl shadow-inner w-full">
+          <div className="flex p-1.5 bg-slate-900/80 backdrop-blur-md rounded-2xl shadow-inner w-full gap-1">
             {[
-              { id: 'CHECK_IN', label: 'Check in', icon: ArrowDownCircle },
-              { id: 'CHECK_OUT', label: 'Check out', icon: ArrowUpCircle },
+              { id: 'CHECK_IN', label: 'Check In', icon: ArrowDownCircle },
+              { id: 'CHECK_OUT', label: 'Check Out', icon: ArrowUpCircle },
               { id: 'TRASH', label: 'Trash', icon: Trash2 }
             ].map((m) => (
               <button
                 key={m.id}
                 onClick={() => setMode(m.id as any)}
                 className={cn(
-                  "flex-1 py-3 rounded-xl text-sm font-black transition-all flex items-center justify-center gap-2",
-                  mode === m.id ? "bg-slate-800 text-primary shadow-lg" : "text-slate-500 hover:text-slate-300"
+                  "flex-1 py-3.5 rounded-xl text-xs sm:text-sm font-black transition-all flex items-center justify-center gap-3",
+                  mode === m.id ? "bg-slate-800 text-primary shadow-lg ring-1 ring-primary/20" : "text-slate-500 hover:text-slate-300"
                 )}
               >
-                <m.icon size={18} />
-                {m.label}
+                <m.icon size={18} className={mode === m.id ? "scale-110 transition-transform" : ""} />
+                <span className="truncate">{m.label}</span>
               </button>
             ))}
           </div>
@@ -558,15 +566,35 @@ export default function Home() {
                   <p className="text-sm text-slate-400">Scan labels to {mode.replace('_', ' ')} items</p>
                 </div>
 
-                <div className="w-full h-px bg-slate-800 my-2" />
+                <div className="w-full h-px bg-slate-800/50 my-2" />
 
-                <button
-                  onClick={() => setShowOnboarding(true)}
-                  className="w-full h-16 rounded-[1.5rem] bg-slate-900/50 border border-slate-800 flex items-center justify-center gap-3 group hover:border-primary/40 transition-all font-bold"
-                >
-                  <Sparkles size={18} className="text-primary group-hover:scale-110 transition-transform" />
-                  <span className="text-sm">Add NEW Item<br />(AI Onboarding)</span>
-                </button>
+                <div className="w-full grid grid-cols-2 gap-3">
+                  <button
+                    onClick={() => setShowOnboarding(true)}
+                    className="flex flex-col items-center justify-center p-5 rounded-3xl bg-indigo-500/10 border border-indigo-500/20 group hover:border-indigo-500/50 transition-all font-black text-indigo-400 gap-3"
+                  >
+                    <div className="p-3 bg-indigo-500/10 rounded-2xl group-hover:scale-110 transition-transform">
+                      <Sparkles size={24} />
+                    </div>
+                    <div className="text-center">
+                      <p className="text-sm leading-tight">Add Item</p>
+                      <p className="text-[10px] opacity-60 font-mono mt-1">AI Onboarding</p>
+                    </div>
+                  </button>
+
+                  <button
+                    onClick={() => setShowBoxManager(true)}
+                    className="flex flex-col items-center justify-center p-5 rounded-3xl bg-slate-900/50 border border-slate-800 group hover:border-primary/40 transition-all font-black text-slate-300 gap-3"
+                  >
+                    <div className="p-3 bg-primary/10 rounded-2xl group-hover:scale-110 transition-transform">
+                      <Package size={24} className="text-primary" />
+                    </div>
+                    <div className="text-center">
+                      <p className="text-sm leading-tight">Manage Boxes</p>
+                      <p className="text-[10px] opacity-60 font-mono mt-1">Box Inventory</p>
+                    </div>
+                  </button>
+                </div>
               </div>
             )}
           </section>
@@ -700,15 +728,54 @@ export default function Home() {
                          </button>
                        </div>
                     </div>
-                    <div className="col-span-2">
-                      <label className="text-xs font-black text-slate-500 ml-1">Specs</label>
-                      <input
-                        type="text"
-                        value={editedItem.specs || ''}
-                        onChange={e => setEditedItem({ ...editedItem, specs: e.target.value })}
+                    <div>
+                      <label className="text-xs font-black text-slate-500 ml-1">Connectors</label>
+                      <input 
+                        type="text" 
+                        value={editedItem.connector || ''} 
+                        onChange={e => setEditedItem({...editedItem, connector: e.target.value})}
                         className="w-full bg-slate-950 border border-slate-800 rounded-xl py-3 px-4 text-sm outline-none text-slate-100"
+                        placeholder="e.g. LC/UPC"
                       />
                     </div>
+                    <div>
+                      <label className="text-xs font-black text-slate-500 ml-1">Size / Length</label>
+                      <input 
+                        type="text" 
+                        value={editedItem.size || ''} 
+                        onChange={e => setEditedItem({...editedItem, size: e.target.value})}
+                        className="w-full bg-slate-950 border border-slate-800 rounded-xl py-3 px-4 text-sm outline-none text-slate-100"
+                        placeholder="e.g. 5m / 10G"
+                      />
+                    </div>
+                    <div className="col-span-2">
+                       <label className="text-xs font-black text-slate-500 ml-1">Color</label>
+                       <input 
+                         type="text" 
+                         value={editedItem.color || ''} 
+                         onChange={e => setEditedItem({...editedItem, color: e.target.value})}
+                         className="w-full bg-slate-950 border border-slate-800 rounded-xl py-3 px-4 text-sm outline-none text-slate-100"
+                         placeholder="e.g. Aqua"
+                       />
+                    </div>
+                    <div className="col-span-2">
+                       <label className="text-xs font-black text-slate-500 ml-1">Description</label>
+                       <textarea
+                         value={editedItem.description || ''}
+                         onChange={e => setEditedItem({ ...editedItem, description: e.target.value })}
+                         className="w-full bg-slate-950 border border-slate-800 rounded-xl py-3 px-4 text-sm outline-none text-slate-100 resize-none h-20"
+                         placeholder="Item description..."
+                       />
+                    </div>
+                    <div className="col-span-2">
+                       <label className="text-xs font-black text-slate-500 ml-1">OCR Matching Key (Local Identification)</label>
+                       <textarea
+                         value={editedItem.ocr_text || ''}
+                         onChange={e => setEditedItem({ ...editedItem, ocr_text: e.target.value })}
+                         className="w-full bg-slate-950 border border-slate-800 rounded-xl py-3 px-4 text-[10px] font-mono outline-none text-slate-400 resize-none h-12"
+                         placeholder="Paste identification string here..."
+                       />
+                    </div>
                   </div>
                 </div>
               ) : (
@@ -852,59 +919,84 @@ export default function Home() {
       {showBoxManager && (
         <div className="fixed inset-0 z-50 flex items-center justify-center p-4 bg-slate-950/90 backdrop-blur-md animate-in fade-in duration-300">
           <div className="w-full max-w-2xl bg-slate-900 border border-slate-800 rounded-[2.5rem] shadow-2xl overflow-hidden flex flex-col max-h-[90vh]">
-            <div className="p-8 border-b border-slate-800 flex justify-between items-center shrink-0 bg-slate-900/50">
-               <div>
-                  <h3 className="text-2xl font-black tracking-tight flex items-center gap-3">
-                    <Package className="text-primary" size={28} />
-                    Box Inventory
-                  </h3>
-                  <p className="text-sm text-slate-500 font-bold mt-1">Manage physical box labels & printing</p>
+            <div className="p-8 pb-4 flex flex-col gap-6 shrink-0 bg-slate-900/50">
+               <div className="flex justify-between items-center">
+                  <div>
+                    <h3 className="text-2xl font-black tracking-tight flex items-center gap-3">
+                      <Package className="text-primary" size={28} />
+                      Box Inventory
+                    </h3>
+                    <p className="text-sm text-slate-500 font-bold mt-1">Manage physical box labels & printing</p>
+                  </div>
+                  <button onClick={() => { setShowBoxManager(false); setBoxSearchQuery(''); }} className="p-3 hover:bg-slate-800 rounded-full transition-colors text-slate-400">
+                    <X size={24} />
+                  </button>
+               </div>
+
+               <div className="relative">
+                 <input 
+                   type="text"
+                   placeholder="Search boxes..."
+                   value={boxSearchQuery}
+                   onChange={(e) => setBoxSearchQuery(e.target.value)}
+                   className="w-full bg-slate-950 border border-slate-800 rounded-2xl py-3.5 pl-11 pr-4 text-sm focus:border-primary outline-none transition-all placeholder:text-slate-600"
+                 />
+                 <Search className="absolute left-4 top-1/2 -translate-y-1/2 text-slate-600" size={18} />
+                 {boxSearchQuery && (
+                   <button 
+                     onClick={() => setBoxSearchQuery('')}
+                     className="absolute right-3 top-1/2 -translate-y-1/2 p-1.5 hover:bg-slate-800 rounded-lg text-slate-500"
+                   >
+                     <X size={14} />
+                   </button>
+                 )}
                </div>
-               <button onClick={() => setShowBoxManager(false)} className="p-3 hover:bg-slate-800 rounded-full transition-colors">
-                  <X size={24} />
-               </button>
             </div>
 
-            <div className="flex-1 overflow-y-auto p-6 space-y-4">
-               {existingBoxes.length === 0 ? (
+            <div className="flex-1 overflow-y-auto p-6 space-y-4 pt-4">
+               {existingBoxes.filter(b => b.toLowerCase().includes(boxSearchQuery.toLowerCase())).length === 0 ? (
                  <div className="py-20 text-center space-y-4 opacity-40">
                     <Package size={48} className="mx-auto" />
-                    <p className="font-bold">No box labels defined yet.</p>
+                    <p className="font-bold">{existingBoxes.length === 0 ? 'No box labels defined yet.' : 'No matching boxes found.'}</p>
                     <p className="text-xs max-w-xs mx-auto">Associate items with a "Box Label" in their metadata to see them here.</p>
                  </div>
                ) : (
-                 <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
-                    {existingBoxes.map(box => {
-                      const itemCount = inventory.filter(i => i.box_label === box).length;
-                      return (
-                        <div key={box} className="bg-slate-950 border border-slate-800 p-5 rounded-3xl flex flex-col gap-4 group hover:border-primary/50 transition-all">
-                           <div className="flex-1 min-w-0">
-                              <h4 className="text-lg font-black text-white truncate">{box}</h4>
-                              <p className="text-xs text-slate-500 font-bold">{itemCount} items linked</p>
-                           </div>
-                           <div className="flex gap-2 shrink-0">
-                              <button 
-                                onClick={() => setSelectedBoxLabel(box)}
-                                className="flex-1 py-3 bg-primary text-white text-xs font-black rounded-xl flex items-center justify-center gap-2 hover:bg-blue-500 transition-colors shadow-lg shadow-primary/20"
-                              >
-                                <Printer size={14} /> Print Label
-                              </button>
-                              <button 
-                                onClick={() => { setSearchQuery(box.toLowerCase()); setShowBoxManager(false); }}
-                                className="px-4 py-3 bg-slate-900 border border-slate-800 text-slate-400 text-xs font-bold rounded-xl hover:bg-slate-800"
-                              >
-                                View
-                              </button>
-                           </div>
-                        </div>
-                      );
-                    })}
+                 <div className="grid grid-cols-1 md:grid-cols-2 gap-3 pb-4">
+                    {existingBoxes
+                      .filter(box => box.toLowerCase().includes(boxSearchQuery.toLowerCase()))
+                      .map(box => {
+                        const itemCount = inventory.filter(i => i.box_label === box).length;
+                        return (
+                          <div key={box} className="bg-slate-950/50 border border-slate-800/60 p-5 rounded-3xl flex flex-col gap-4 group hover:border-primary/40 transition-all">
+                             <div className="flex-1 min-w-0">
+                                <h4 className="text-lg font-black text-white truncate">{box}</h4>
+                                <p className="text-xs text-slate-500 font-bold mt-0.5">{itemCount} items linked</p>
+                             </div>
+                             <div className="flex gap-2 shrink-0">
+                                <button 
+                                  onClick={() => setSelectedBoxLabel(box)}
+                                  className="flex-1 py-3 bg-primary text-white text-[11px] font-black rounded-xl flex items-center justify-center gap-2 hover:bg-blue-500 transition-colors shadow-lg shadow-primary/10 active:scale-95"
+                                >
+                                  <Printer size={14} /> Print Label
+                                </button>
+                                <button 
+                                  onClick={() => { setSearchQuery(box.toLowerCase()); setShowBoxManager(false); setBoxSearchQuery(''); }}
+                                  className="px-4 py-3 bg-slate-900 border border-slate-800 text-slate-400 text-[11px] font-bold rounded-xl hover:bg-slate-800 active:scale-95"
+                                >
+                                  View
+                                </button>
+                             </div>
+                          </div>
+                        );
+                      })}
                  </div>
                )}
             </div>
             
-            <div className="p-6 bg-slate-950/50 border-t border-slate-800 text-center">
-               <p className="text-[10px] text-slate-600 font-bold uppercase tracking-widest">TFM aInventory • Box Management Mode</p>
+            <div className="p-6 py-4 bg-slate-950/50 border-t border-slate-800 text-center flex items-center justify-center gap-2">
+               <div className="w-1 h-1 rounded-full bg-primary animate-pulse" />
+               <p className="text-[10px] text-slate-500 font-bold font-mono">TFM aInventory • Box management mode</p>
+            </div>
             </div>
           </div>
         </div>

frontend/components/AIOnboarding.tsx

@@ -73,8 +73,12 @@ export default function AIOnboarding({ onCancel, onComplete, categories, invento
       type: extractedData.type ? String(extractedData.type) : null,
       part_number: extractedData.part_number ? String(extractedData.part_number) : null,
       color: extractedData.color ? String(extractedData.color) : null,
-      specs: String(extractedData.specs || ""),
-      barcode: String(extractedData.barcode || extractedData.part_number || extractedData.serial_number || `AI-${Date.now()}`),
+      description: String(extractedData.description || ""),
+      connector: extractedData.connector ? String(extractedData.connector) : null,
+      size: extractedData.size ? String(extractedData.size) : null,
+      ocr_text: extractedData.ocr_text ? String(extractedData.ocr_text) : null,
+      specs: String(extractedData.specs || ""), // Keep specs as extra data if needed
+      barcode: String(extractedData.barcode || extractedData.part_number || `AI-${Date.now()}`),
       quantity: parseFloat(String(extractedData.quantity || 1)),
       min_quantity: 1.0,
       box_label: extractedData.box_label ? String(extractedData.box_label) : null,
@@ -273,12 +277,46 @@ export default function AIOnboarding({ onCancel, onComplete, categories, invento
             </div>
 
             <div className="bg-slate-900/80 p-5 rounded-[1.5rem] border border-slate-800 focus-within:border-primary/50 transition-colors group">
-              <label className="text-xs text-slate-500 font-bold mb-1 block group-focus-within:text-primary transition-colors">Technical Specifications</label>
+              <label className="text-xs text-slate-500 font-bold mb-1 block group-focus-within:text-primary transition-colors">Description</label>
               <textarea 
-                value={extractedData.specs || ''} 
-                onChange={(e) => setExtractedData({...extractedData, specs: e.target.value})}
-                className="bg-transparent w-full text-sm leading-relaxed outline-none resize-none h-20 text-slate-300"
-                placeholder="Technical details..."
+                value={extractedData.description || ''} 
+                onChange={(e) => setExtractedData({...extractedData, description: e.target.value})}
+                className="bg-transparent w-full text-sm leading-relaxed outline-none resize-none h-16 text-slate-300"
+                placeholder="Product description..."
+              />
+            </div>
+
+            <div className="grid grid-cols-2 gap-4">
+               <div className="bg-slate-900/80 p-5 rounded-[1.5rem] border border-slate-800 focus-within:border-primary/50 transition-colors group">
+                <label className="text-xs text-slate-500 font-bold mb-1 block group-focus-within:text-primary transition-colors">Connector</label>
+                <input 
+                  value={extractedData.connector || ''} 
+                  onChange={(e) => setExtractedData({...extractedData, connector: e.target.value})}
+                  className="bg-transparent w-full font-bold outline-none text-slate-200"
+                  placeholder="e.g. LC/UPC"
+                />
+              </div>
+              <div className="bg-slate-900/80 p-5 rounded-[1.5rem] border border-slate-800 focus-within:border-primary/50 transition-colors group">
+                <label className="text-xs text-slate-500 font-bold mb-1 block group-focus-within:text-primary transition-colors">Size / Length</label>
+                <input 
+                  value={extractedData.size || ''} 
+                  onChange={(e) => setExtractedData({...extractedData, size: e.target.value})}
+                  className="bg-transparent w-full font-bold outline-none text-slate-200"
+                  placeholder="e.g. 5m / 10G"
+                />
+              </div>
+            </div>
+
+            <div className="bg-slate-900 border-2 border-primary/20 p-5 rounded-[1.5rem] shadow-lg">
+              <div className="flex items-center gap-2 mb-2 text-primary">
+                 <Sparkles size={14} />
+                 <label className="text-xs font-black uppercase tracking-tighter">AI OCR Matching Key</label>
+              </div>
+              <textarea 
+                value={extractedData.ocr_text || ''} 
+                onChange={(e) => setExtractedData({...extractedData, ocr_text: e.target.value})}
+                className="bg-transparent w-full text-[10px] font-mono leading-tight outline-none resize-none h-12 text-slate-400"
+                placeholder="Heuristic string for local matching..."
               />
             </div>
 

frontend/entrypoint.sh

@@ -14,6 +14,17 @@ if [ -d "/app/logs" ]; then
     chown -R nextjs:nodejs /app/logs
 fi
 
+# Generate network.json for frontend runtime discovery
+echo "🐳 [Docker] Generating public/network.json..."
+cat <<EOF > /app/public/network.json
+{
+  "SERVER_IP": "${SERVER_IP:-localhost}",
+  "BACKEND_PORT": ${BACKEND_PORT:-8000},
+  "BACKEND_SSL_PORT": ${BACKEND_SSL_PORT:-8908}
+}
+EOF
+chown nextjs:nodejs /app/public/network.json
+
 # Hand off to the application server as the nextjs user
 echo "🐳 [Docker] Starting Next.js standalone server as nextjs user..."
 exec su-exec nextjs node server.js

frontend/lib/api.ts

@@ -220,5 +220,32 @@ export const inventoryApi = {
   updateDbSettings: async (settings: any) => {
     const res = await axiosInstance.patch('/admin/db/settings', settings);
     return res.data;
+  },
+  exportDb: async () => {
+    const res = await axiosInstance.get('/admin/db/export', { responseType: 'blob' });
+    return res.data;
+  },
+  importDb: async (formData: FormData) => {
+    const res = await axiosInstance.post('/admin/db/import', formData, {
+      headers: { 'Content-Type': 'multipart/form-data' }
+    });
+    return res.data;
+  },
+  // System Settings
+  getSystemSettings: async () => {
+    // Note: Reusing the existing settings router pattern but adding AI Prompt
+    const res = await axiosInstance.get('/admin/db/settings');
+    // We need another endpoint for general settings or expand the DB one
+    // For now, I'll add a specific fetch for the prompt
+    const promptRes = await axiosInstance.get('/admin/db/settings/prompt');
+    return { ...res.data, ai_extraction_prompt: promptRes.data.value };
+  },
+  getAiPrompt: async () => {
+    const res = await axiosInstance.get('/admin/db/settings/prompt');
+    return res.data;
+  },
+  updateAiPrompt: async (prompt: string) => {
+    const res = await axiosInstance.post('/admin/db/settings/prompt', { value: prompt });
+    return res.data;
   }
 };

frontend/lib/db.ts

@@ -15,6 +15,10 @@ export interface Item {
   labels_data?: string;
   serial_number?: string;
   type?: string;
+  description?: string;
+  connector?: string;
+  size?: string;
+  ocr_text?: string;
 }
 
 export interface PendingOperation {
@@ -34,8 +38,8 @@ export class InventoryDatabase extends Dexie {
 
   constructor() {
     super('InventoryDatabase');
-    this.version(4).stores({
-      items: '++id, barcode, name, category, part_number, color, box_label',
+    this.version(5).stores({
+      items: '++id, barcode, name, category, part_number, color, box_label, ocr_text',
       pendingOperations: '++id, barcode, timestamp, synced, uuid'
     });
   }

frontend/public/network.json

@@ -0,0 +1,7 @@
+{
+  "SERVER_IP": "192.168.84.113",
+  "BACKEND_PORT": 8916,
+  "BACKEND_SSL_PORT": 8918,
+  "FRONTEND_PORT": 8917,
+  "FRONTEND_SSL_PORT": 8919
+}

inventory.env

@@ -0,0 +1,24 @@
+# =============================================================================
+# TFM aInventory - Docker Compose Environment
+# =============================================================================
+# This file is used by Docker Compose for host-side port mapping.
+# It should match the values in config/network_config.env
+# =============================================================================
+
+SERVER_IP=192.168.84.113
+
+# Backend Ports
+BACKEND_PORT=8916
+BACKEND_SSL_PORT=8918
+
+# Frontend Ports
+FRONTEND_PORT=8917
+FRONTEND_SSL_PORT=8919
+
+# Security & AI
+JWT_SECRET_KEY=change_me_in_production
+GEMINI_API_KEY=AIzaSyAajthWG2agpDLyJHY11U5qFLP4WnV5z0w
+
+# External Access (CORS)
+# Comma-separated list of extra IPs or FQDNs allowed to connect (e.g. Tailscale, VPN)
+EXTRA_ALLOWED_ORIGINS=100.78.182.27

run_standalone.sh

@@ -7,7 +7,7 @@ echo "🚀 Starting TFM aInventory in Standalone Mode..."
 # Trapping termination signals to clean up child processes
 trap "echo 'Stopping all processes...'; kill 0" SIGINT SIGTERM EXIT
 
-# --- CONFIGURATION (Default values, overridden by network_config.env) ---
+# --- CONFIGURATION (Default values, overridden by network_configinventory.env) ---
 BACKEND_PORT=8000
 FRONTEND_PORT=3001
 BACKEND_SSL_PORT=3002
@@ -15,7 +15,7 @@ FRONTEND_SSL_PORT=3003
 SERVER_IP="localhost"
 
 # Load Configuration from file if it exists
-CONFIG_PATH="$(cd "$(dirname "$0")" && pwd)/.env"
+CONFIG_PATH="$(cd "$(dirname "$0")" && pwd)/inventory.env"
 if [ -f "$CONFIG_PATH" ]; then
     echo "⚙️  Loading network configuration from $CONFIG_PATH..."
     export $(grep -v '^#' "$CONFIG_PATH" | xargs)

start_server.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# --- CONFIGURATION (Default values, will be overridden by network_config.env) ---
+# --- CONFIGURATION (Default values, will be overridden by network_configinventory.env) ---
 BACKEND_PORT=8000
 FRONTEND_PORT=3001
 BACKEND_SSL_PORT=3002
@@ -8,10 +8,10 @@ FRONTEND_SSL_PORT=3003
 SERVER_IP="localhost"
 
 # Load Configuration from file if it exists
-CONFIG_PATH="$(cd "$(dirname "$0")" && pwd)/.env"
+CONFIG_PATH="$(cd "$(dirname "$0")" && pwd)/inventory.env"
 if [ -f "$CONFIG_PATH" ]; then
     echo "⚙️  Loading network configuration from $CONFIG_PATH..."
-    # Export variables from .env file (ignoring comments and empty lines)
+    # Export variables from inventory.env file (ignoring comments and empty lines)
     export $(grep -v '^#' "$CONFIG_PATH" | xargs)
 fi
 
@@ -87,9 +87,19 @@ echo -e "${GREEN}=======================================================${NC}"
 echo -e "${GREEN}${BOLD}        🚀 TFM aInventory UNIFIED ACCESS${NC}"
 echo -e "${GREEN}=======================================================${NC}"
 echo ""
-echo -e "   USE THIS URL ON BOTH DESKTOP & MOBILE:"
-echo -e "   👉 ${GREEN}${BOLD}https://$LOCAL_IP:$FRONTEND_SSL_PORT${NC}"
-echo -e "   (Or ${GREEN}https://localhost:$FRONTEND_SSL_PORT${NC} on this Mac)"
+   echo -e "   USE THIS URL ON BOTH DESKTOP & MOBILE:"
+   echo -e "   👉 ${GREEN}${BOLD}https://$LOCAL_IP:$FRONTEND_SSL_PORT${NC}"
+   echo -e "   (Or ${GREEN}https://localhost:$FRONTEND_SSL_PORT${NC} on this Mac)"
+
+   if [ ! -z "$EXTRA_ALLOWED_ORIGINS" ]; then
+       echo -e "   EXTERNAL/VPN ACCESS points:"
+       IFS=',' read -ra ADDR <<< "$EXTRA_ALLOWED_ORIGINS"
+       for exp in "${ADDR[@]}"; do
+           # Trim spaces and print
+           TRIMMED=$(echo $exp | xargs)
+           echo -e "   👉 ${GREEN}${BOLD}https://$TRIMMED:$FRONTEND_SSL_PORT${NC}"
+       done
+   fi
 echo ""
 echo -e "   ${YELLOW}${BOLD}NOTE:${NC} If you see a 'Not Private' warning,"
 echo -e "   Click 'Advanced' -> 'Proceed' to continue."