forgecad 0.9.14 → 0.9.16

package/dist/docs-raw/product/user-outreach-email-templates.md

@@ -1,161 +0,0 @@
-# User Outreach Email Templates
-
-This is a tactical product doc. For the product-first theme map, start with [Product Docs](README.md).
-
-Use these templates for personal outreach to ForgeCAD users. They are intentionally written in a founder/operator voice: warm, specific, curious, and useful. The goal is to learn from real projects, make users feel supported, and open the door to deeper onboarding when it makes sense.
-
-## Shared Guidance
-
-- Personalize the first sentence with one real signal when possible: plan tier, recent activity, project name, export type, team domain, or signup source.
-- Keep the ask small. A 20-minute chat is easier to accept than a vague "feedback call."
-- Do not make the user prove they are important. The default posture is: if they are using ForgeCAD, their workflow matters.
-- For Pro users, make support and team onboarding explicit. They already crossed the trust line.
-- For active free users, lead with curiosity. Mention Pro only as a practical fit for commercial work, not as the reason for the email.
-
-## Pro User Templates
-
-### 1. Welcome And Use Case Discovery
-
-**Subject:** Welcome to ForgeCAD Pro
-
-Hi {{first_name}},
-
-I saw that you upgraded to ForgeCAD Pro. Thank you for trusting us with your work.
-
-I wanted to reach out personally because we are still early enough that real professional use cases can directly shape the product. If you are using ForgeCAD for client work, a product, internal tooling, robotics, 3D printing, fixtures, or anything else serious, I would love to understand what you are building and where the tool should become sharper for you.
-
-Would you be open to a 20-minute call this week or next? I can help with onboarding, answer workflow questions, and learn what would make ForgeCAD more useful for your day-to-day work.
-
-Best,
-
-{{sender_name}}
-
-### 2. Team Onboarding Exploration
-
-**Subject:** Helping your team get further with ForgeCAD
-
-Hi {{first_name}},
-
-Thanks again for using ForgeCAD Pro. I wanted to check whether you are using it mostly on your own, or whether there are other people on your team who might need to work with the same models, project files, exports, or review flow.
-
-If there is a team workflow behind your ForgeCAD use, I would be happy to help you think through the setup: local project structure, CLI usage, shared browser projects, AI-assisted modeling, exports, and any support expectations around commercial work.
-
-Would it be useful to set up a short onboarding call? Even if you are not ready to add more people yet, it would help us understand what serious team adoption should feel like.
-
-Best,
-
-{{sender_name}}
-
-### 3. Pro Check-In After Usage
-
-**Subject:** How is ForgeCAD Pro fitting into your work?
-
-Hi {{first_name}},
-
-I wanted to check in now that you have had some time with ForgeCAD Pro.
-
-The main thing I would love to understand is: what job are you trying to get done with ForgeCAD, and where does the product currently help the most or slow you down?
-
-If you have a real project in progress, I am happy to look at the workflow with you. A short call would help us support you better, and it would also help us decide which Pro and team features should come next.
-
-Best,
-
-{{sender_name}}
-
-## Active User Templates
-
-### 1. Curious Product Discovery
-
-**Subject:** Curious what you are building with ForgeCAD
-
-Hi {{first_name}},
-
-I noticed you have been active in ForgeCAD recently, and I wanted to reach out personally.
-
-We are trying to understand what people are actually building: quick 3D-printable parts, mechanical assemblies, robotics ideas, fixtures, generated geometry, design automation, or something completely different. The product gets much better when we can see the real use cases behind the activity.
-
-Would you be open to a 20-minute chat? I would mostly like to learn what you are working on, what feels promising, and what currently gets in your way.
-
-Best,
-
-{{sender_name}}
-
-### 2. Active User With Commercial Hint
-
-**Subject:** Learning from your ForgeCAD workflow
-
-Hi {{first_name}},
-
-I saw you have been using ForgeCAD and wanted to ask what kind of work you are exploring with it.
-
-If this is personal, learning, open-source, or experimental work, I would simply love to understand the project and what would make ForgeCAD more enjoyable or capable for you. If you are using it commercially, ForgeCAD Pro may be the right fit, and I am happy to explain that too, but that is not the main reason I am writing.
-
-The main reason is that active users teach us where the product is strong, where it is confusing, and what workflows deserve more attention.
-
-Would you be open to a quick call?
-
-Best,
-
-{{sender_name}}
-
-### 3. High-Activity User Check-In
-
-**Subject:** Quick ForgeCAD question
-
-Hi {{first_name}},
-
-I noticed you have spent real time with ForgeCAD, so I wanted to ask one direct question:
-
-What are you trying to make with it?
-
-We are early, and this is the stage where understanding real projects matters more than polished surveys. If ForgeCAD is helping, I would like to know why. If something is awkward, missing, or confusing, I would like to know that even more.
-
-Would you be open to a short chat this week or next?
-
-Best,
-
-{{sender_name}}
-
-## Follow-Up Templates
-
-### 1. Gentle Follow-Up
-
-**Subject:** Re: {{previous_subject}}
-
-Hi {{first_name}},
-
-Just wanted to follow up once in case this got buried.
-
-I would still be very interested to hear what you are using ForgeCAD for. Even a two-sentence reply would be useful if a call is too much right now.
-
-Best,
-
-{{sender_name}}
-
-### 2. Concrete Reply Prompt
-
-**Subject:** Re: {{previous_subject}}
-
-Hi {{first_name}},
-
-One quick follow-up. If a call is not convenient, could you reply with whichever of these is closest?
-
-1. I am using ForgeCAD for personal projects or learning.
-2. I am evaluating it for commercial work.
-3. I am trying to use it with a team.
-4. I am stuck or missing something important.
-
-That alone would help us understand how to support you better.
-
-Best,
-
-{{sender_name}}
-
-## Placeholder Checklist
-
-| Placeholder | Meaning |
-|---|---|
-| `{{first_name}}` | User first name when known, otherwise use `there` |
-| `{{sender_name}}` | Founder/operator name |
-| `{{previous_subject}}` | Subject line from the first outreach email |
-| `{{project_signal}}` | Optional project, command, export, or activity signal for manual personalization |

package/dist/docs-raw/product/user-segments.md

@@ -1,15 +0,0 @@
-# User Segments
-
-ForgeCAD has several possible audiences. They should not be mixed too early.
-
-The first wedge is the AI-first maker. This user owns or can access a 3D printer, laser cutter, CNC service, or online manufacturing service. They may know a little JavaScript, but they do not want to become a professional CAD operator. They want an agent to help make useful objects and they want enough control to trust the result.
-
-The adjacent daily user is the creative manufacturing user. They may not care about code at all. They want a custom adapter, shelf part, enclosure, stand, organizer, jig, toy, lamp, or furniture fitting. For this person, ForgeCAD should feel like a practical object generator with editable parameters, not a programming environment.
-
-The technical evaluator is a software engineer, automation engineer, robotics builder, or mechanical designer exploring whether code-first CAD fits a workflow. This user cares about repeatability, versioning, export quality, CLI checks, and whether the product can fit into a larger system.
-
-The partner user is a company that wants physical customization inside an existing product surface. A 3D printer app, furniture site, marketplace, education product, robotics workflow, or custom-product storefront does not necessarily want a whole CAD system. It wants a safe parametric generator that can be embedded, constrained, validated, and exported.
-
-The enterprise AI-CAD user is later and more specialized. They may want benchmarks, data, evaluation loops, backend routing, training workflows, or integrations with existing CAD systems. This segment can produce revenue and strategic pull, but it should not dilute the first product message.
-
-The product should be honest about which segment each feature serves. A feature can serve multiple segments, but the first reason to build it should be clear.

package/dist/docs-raw/product/vision.md

@@ -1,26 +0,0 @@
-# Vision
-
-ForgeCAD is not mainly a CAD library. It is an AI-native interface layer for physical design.
-
-Traditional CAD assumes the human directly manipulates a complex model through a GUI. Classic CAD-as-code assumes the human writes the model. ForgeCAD assumes the human expresses a goal, the AI authors editable semantic code, and the system validates whether the result is real enough to manufacture.
-
-That distinction matters because AI needs a surface it can understand, edit, test, and repair. Binary model state is hard for an agent to reason about. A purely visual prompt-to-mesh result can look impressive but fail when the user needs a parameter changed, a hole moved, or a manufacturing export produced. ForgeCAD's product bet is that the best AI CAD interface is a readable representation of design intent, plus a validation loop.
-
-The backend should be chosen after the intent is clear. Fast browser preview, exact STEP export, STL/3MF printing, sheet output, robot packages, furniture cut lists, and future CNC routes are different output needs. The product should own the semantic intent layer and the workflow that turns intent into evidence.
-
-The long-term product is therefore not "another geometry kernel." Geometry kernels are suppliers. ForgeCAD's durable product position is the language, workflow, validation evidence, project system, and partner surface through which AI creates editable physical objects.
-
-The simple framing is:
-
-```text
-traditional CAD:
-human intent -> GUI operations -> proprietary model state -> export
-
-classic CAD-as-code:
-human intent -> code -> geometry kernel -> export
-
-ForgeCAD:
-human goal + feedback -> AI-authored semantic code -> validation loop -> chosen backend/export
-```
-
-The product should be judged by how well it makes that third loop reliable for real users.

package/dist/docs-raw/rl-environments.md

@@ -1,350 +0,0 @@
-# ForgeCAD RL Environments
-
-This is the permanent operating guide for ForgeCAD reinforcement-learning and
-AI-lab reconstruction environments.
-
-## Product Goal
-
-ForgeCAD RL environments should let an external lab train or evaluate an agent
-that turns reference physical geometry into readable ForgeCAD source code.
-
-Harbor is the executable contract. ForgeCAD keeps the product code, verifier
-integration, benchmark import tools, and public leaderboard page. The Harbor
-task corpus lives outside this repository.
-
-## Repository Split
-
-Use two neighboring checkouts:
-
-```text
-~/Projects/CAD/
-  ForgeCAD/
-    ai-labs/reconstruction-benchmark/
-    src/pages/generatedBenchmarkData.ts
-  ForgeCAD-Harbor-Datasets/
-    reconstruction/
-      dataset.toml
-      agents/
-      tasks/
-```
-
-The ForgeCAD repo discovers the external dataset from:
-
-```bash
-FORGECAD_RECONSTRUCTION_DATASET_ROOT="$HOME/Projects/CAD/ForgeCAD-Harbor-Datasets/reconstruction"
-```
-
-If the variable is not set, the local tools default to:
-
-```text
-../ForgeCAD-Harbor-Datasets/reconstruction
-```
-
-The external collaboration repository for SpaceXAI-facing handoff material is:
-
-```text
-https://github.com/KoStard/SpaceXAI_ForgeCAD
-```
-
-Treat that repository as coordination and distribution context. The executable
-task contract is the Harbor dataset.
-
-## Harbor Task Contract
-
-Each external task folder includes:
-
-```text
-README.md
-instruction.md
-task.toml
-environment/
-  Dockerfile
-  forgecad-wrapper.sh
-  reference/<task-reference>.3mf
-  starter/main.forge.js
-tests/
-  test.sh
-  checks.py
-  enrich-reward.mjs
-  forgecad-reconstruction-check.mjs
-  score-calibration.mjs
-  task.json
-```
-
-The agent sees the reference asset, starter source, instructions, and the
-workspace-local `forgecad` wrapper. The verifier files under `tests/` are hidden
-until the agent exits.
-
-The final answer is always:
-
-```text
-/app/submission/main.forge.js
-```
-
-The answer must be editable parametric ForgeCAD source. It must not import,
-read, embed, copy, or encode the reference asset.
-
-The `forgecad` wrapper exposes run/render/inspect/export checks but blocks
-direct `score` and `compare` use during the episode. The hidden verifier uses
-the internal comparison path after the agent exits.
-
-Verifier execution goes through RewardKit:
-
-```bash
-uvx --from 'harbor-rewardkit==0.1.*' rewardkit /tests
-```
-
-`checks.py` exposes one programmatic criterion,
-`forgecad_reconstruction_score`, backed by the ForgeCAD guard/render/compare
-script. RewardKit writes `/logs/verifier/reward.json` and
-`/logs/verifier/reward-details.json`; `enrich-reward.mjs` preserves the
-RewardKit output while ensuring `reward.json` has numeric Harbor fields:
-`reward`, `score`, `rawCompareScore`, `guard`, and `valid`.
-
-## Command Surface
-
-Run agents through Harbor directly:
-
-```bash
-uvx --from harbor harbor run \
-  -p "$FORGECAD_RECONSTRUCTION_DATASET_ROOT/tasks" \
-  --include-task-name ball-bearing \
-  --agent codex \
-  --model gpt-5.5 \
-  --artifact /app/submission/main.forge.js \
-  --jobs-dir "$HOME/Projects/CAD/ForgeCAD-RL-Agent-Runs/harbor/codex" \
-  --n-concurrent 1
-```
-
-Use the ForgeCAD repo only for reporting:
-
-```bash
-npm run benchmark:reconstruction:list
-npm run benchmark:reconstruction:import-harbor -- <job-or-trial-dir> --budget standard
-npm run benchmark:reconstruction:leaderboard
-npm run benchmark:reconstruction:report
-npm run build:benchmark-data
-```
-
-There is no ForgeCAD-owned task sync command. If Harbor can run the external
-dataset path, the benchmark layer can import the resulting jobs.
-
-## Direct Harbor Runs
-
-### One Task, One Agent
-
-Use `--include-task-name` to select one Harbor task. Use `--agent` for a
-built-in Harbor agent:
-
-```bash
-CODEX_AUTH_JSON_PATH="$HOME/.codex/auth.json" \
-uvx --from harbor harbor run \
-  -p "$FORGECAD_RECONSTRUCTION_DATASET_ROOT/tasks" \
-  --include-task-name ball-bearing \
-  --agent codex \
-  --model gpt-5.5 \
-  --artifact /app/submission/main.forge.js \
-  --jobs-dir "$HOME/Projects/CAD/ForgeCAD-RL-Agent-Runs/harbor/codex" \
-  --n-concurrent 1
-```
-
-Use `--agent-import-path` for a custom adapter such as the bundled Grok adapter:
-
-```bash
-PYTHONPATH="$FORGECAD_RECONSTRUCTION_DATASET_ROOT/agents" \
-GROK_AUTH_JSON="$HOME/.grok/auth.json" \
-GROK_CONFIG_TOML="$HOME/.grok/config.toml" \
-uvx --from harbor harbor run \
-  -p "$FORGECAD_RECONSTRUCTION_DATASET_ROOT/tasks" \
-  --include-task-name ball-bearing \
-  --agent-import-path grok_harbor_agent:GrokCliAgent \
-  --model grok-build \
-  --artifact /app/submission/main.forge.js \
-  --jobs-dir "$HOME/Projects/CAD/ForgeCAD-RL-Agent-Runs/harbor/grok" \
-  --n-concurrent 1
-```
-
-### Full Suite
-
-Codex:
-
-```bash
-CODEX_AUTH_JSON_PATH="$HOME/.codex/auth.json" \
-uvx --from harbor harbor run \
-  -p "$FORGECAD_RECONSTRUCTION_DATASET_ROOT/tasks" \
-  --agent codex \
-  --model gpt-5.5 \
-  --jobs-dir "$HOME/Projects/CAD/ForgeCAD-RL-Agent-Runs/harbor/codex" \
-  --artifact /app/submission/main.forge.js \
-  --n-concurrent 3
-```
-
-Grok:
-
-```bash
-PYTHONPATH="$FORGECAD_RECONSTRUCTION_DATASET_ROOT/agents" \
-GROK_AUTH_JSON="$HOME/.grok/auth.json" \
-GROK_CONFIG_TOML="$HOME/.grok/config.toml" \
-uvx --from harbor harbor run \
-  -p "$FORGECAD_RECONSTRUCTION_DATASET_ROOT/tasks" \
-  --agent-import-path grok_harbor_agent:GrokCliAgent \
-  --model grok-build \
-  --jobs-dir "$HOME/Projects/CAD/ForgeCAD-RL-Agent-Runs/harbor/grok" \
-  --artifact /app/submission/main.forge.js \
-  --n-concurrent 3
-```
-
-Direct Harbor CLI-agent runs need outbound internet from the task container for
-agent install/auth/model calls, so the task definitions set
-`allow_internet = true`. The verifier remains hidden until the agent exits.
-
-## Run Data And Leaderboard
-
-Keep run outputs outside the source checkout:
-
-```text
-~/Projects/CAD/ForgeCAD-RL-Agent-Runs/
-  harbor/
-    <agent>/<job>/
-  benchmark/main/
-    submissions.jsonl
-    submissions/
-    leaderboard.json
-    leaderboard.md
-    report/
-```
-
-Raw Harbor jobs are evidence. Keep them somewhere durable, but do not commit
-them to ForgeCAD. They contain logs, generated code, renders, verifier payloads,
-local paths, and provider-specific artifacts.
-
-Important Harbor files:
-
-```text
-<jobs-dir>/<timestamp>/<task-trial>/
-  result.json
-  trial.log
-  artifacts/main.forge.js
-  verifier/reward.json
-  verifier/reward-details.json
-  verifier/report.json
-  verifier/score.json
-  verifier/submission.png
-  verifier/reference.png
-```
-
-The public leaderboard is updated by importing selected Harbor jobs into the
-local benchmark ledger, regenerating reports, then regenerating the repo-safe
-snapshot:
-
-```bash
-npm run benchmark:reconstruction:import-harbor -- \
-  "$HOME/Projects/CAD/ForgeCAD-RL-Agent-Runs/harbor/codex/<job>" \
-  --budget standard
-npm run benchmark:reconstruction:report
-npm run build:benchmark-data
-```
-
-Commit `src/pages/generatedBenchmarkData.ts` to publish the website update.
-The committed snapshot contains only sanitized task, model, score, reward,
-metric, and timing fields. It does not contain raw logs or private paths.
-
-## Result Payload Contract
-
-The Harbor verifier writes numeric reward files:
-
-| Field | Purpose |
-|---|---|
-| `reward` | Scalar in `[0, 1]` for RL. |
-| `score` | Human scale score in `[0, 100]`, normally `reward * 100`. |
-| `rawCompareScore` | Raw ForgeCAD geometry comparison score before calibration. |
-| `guard` | Numeric guardrail pass marker. |
-| `valid` | Numeric validity marker. |
-
-Harbor reward values must stay numeric because Harbor validates reward payloads
-as scalar metrics. Detailed status, aggregation, guard issues, score vectors,
-renders, and command logs live in `/logs/verifier/report.json`,
-`/logs/verifier/score.json`, `/logs/verifier/reward-details.json`, and the
-copied Harbor trial artifacts.
-
-## Scoring Principles
-
-The scalar reward is a projection, not the whole truth. Keep the score vector
-first-class.
-
-For reconstruction tasks, the geometry component should include:
-
-- Bidirectional surface coverage over multiple thresholds.
-- Tail-distance penalties such as p95/p99.
-- Feature-edge matching for sharp and boundary structure.
-- Dimension agreement.
-- Volume or occupancy overlap where reliable.
-- Hard caps for obvious shortcut failures.
-
-Avoid solving score problems by only changing a curve shape. If a two-ring
-bearing approximation scores too high, the missing signal is structural:
-rolling elements, feature edges, component count, section occupancy, or
-topology. Add the missing measurement and then calibrate the scalar projection.
-
-## Maintaining Tasks
-
-When adding or changing a task, edit the external Harbor dataset. Keep task IDs
-user-facing, include the full Harbor layout, record reference SHA-256 in
-`tests/task.json`, and keep `/app/submission/main.forge.js` as the stable
-deliverable.
-
-Run enough Harbor jobs to prove the task behaves correctly: reference identity
-scoring, starter scoring, at least one weak shortcut candidate, and one stronger
-candidate. The stronger candidate should rank higher for the right reasons.
-
-## Maintaining Agent Adapters
-
-Agent adapters belong with the external Harbor dataset. For each supported
-Harbor agent CLI, keep a short note answering:
-
-1. How to run headlessly.
-2. How to set cwd.
-3. How to set task-local home/config.
-4. How skills are discovered.
-5. How to disable global/user config.
-6. How to disable web search, subagents, plugins, MCP, and memory.
-7. What filesystem sandbox exists.
-8. How auth is supplied.
-9. How stdin is made non-interactive.
-10. How logs are captured.
-11. How the wall-clock timeout is enforced.
-
-Promote stable CLI adapter facts here when they become part of the supported
-contract.
-
-## Versioning Policy
-
-Version every surface that labs depend on:
-
-- Harbor dataset digest.
-- Task IDs.
-- `tests/task.json` schema fields.
-- Verifier payload shape.
-- Score aggregation profile.
-- Geometry comparison algorithm version.
-
-Changing the scalar reward is a benchmark change. Keep the score vector and raw
-compare metrics in the payload so old and new rewards can be compared across
-saved runs.
-
-## Merge Readiness Checklist
-
-Before merging reconstruction environment changes:
-
-1. `npm test` passes, or a narrower check is justified in the PR.
-2. `npm run benchmark:reconstruction:list` passes against the external dataset.
-3. Harbor can run the changed task directly from the external dataset.
-4. Verifier reward output contains numeric `reward`, `score`,
-   `rawCompareScore`, `guard`, and `valid`.
-5. Verifier report output contains the detailed status, score vector,
-   aggregation, guard data, and artifacts.
-6. RewardKit writes `reward-details.json`.
-7. Agent logs are captured in the Harbor trial folder.
-8. Timeouts are enforced by Harbor and inside the verifier.
-9. No global skills or parent repo instructions are required.
-10. The docs index and this guide are updated when the contract changes.