forgecad 0.9.13 → 0.9.15

package/dist/docs-raw/product/onboarding-first-experience.md

@@ -1,256 +0,0 @@
-# First Account Onboarding Experience
-
-This is a tactical product doc. For the product-first theme map, start with [Product Docs](README.md).
-
-This is the source of truth for the first experience after a person creates a ForgeCAD account.
-
-Any code, docs copy, starter files, CLI guidance, analytics, or launch issue that changes first-run behavior should start by updating this document. The goal is to keep the experience coherent instead of letting it drift across auth, project creation, examples, docs, and CLI surfaces.
-
-## Summary
-
-The first account experience should not drop a new user into an empty editor. A new user should land in a small "Start Here" project with three curated files, a visible docs Welcome page, and a clear path from browser exploration to CLI-based local work.
-
-The recommended first-run path is:
-
-1. Account is created.
-2. User opens `/app`.
-3. If the account has no projects, ForgeCAD creates a private `Start Here` project from the starter template.
-4. The editor opens `00-start-here.forge.js`.
-5. The file itself teaches the first model loop: edit one parameter, run, see geometry change.
-6. The docs nav exposes `/docs/welcome` as the public orientation page.
-7. The Welcome page points to the CLI loop and API docs without making the user read the whole docs set first.
-
-## Decision
-
-Use a curated starter project as the first account artifact. Do not open the full examples project by default for hosted accounts.
-
-The full examples project is too large for first contact. It is useful once the person already knows what kind of thing they are looking for. A first account needs something smaller: one runnable file, one slightly richer parametric file, and one assembly file.
-
-## User Profiles
-
-### Alex - AI-First Maker
-
-**Background:** Uses Codex or Claude Code daily, knows JavaScript well enough to edit generated code, owns a 3D printer.
-
-**What Alex Wants:**
-
-- Get from idea to printable geometry quickly.
-- Ask an AI agent to change a model and validate it through the CLI.
-- Understand which files matter without reading a large reference.
-- Export STL or images from the terminal.
-
-**Ideal Flow:**
-
-```bash
-npm install -g forgecad
-forgecad login
-forgecad project clone start-here
-cd start-here
-forgecad run 00-start-here.forge.js
-forgecad studio .
-```
-
-For GitHub/Google accounts, `forgecad login` should offer API-token login because there is no CLI password to submit.
-
-**Current Friction:**
-
-- A new account sees a blank or near-empty editor state.
-- The CLI is not part of the first-run path.
-- The AI skill exists but is not connected to the account onboarding story.
-
-### Maya - Mechanical Designer Trying Code-CAD
-
-**Background:** Comfortable with CAD concepts, not necessarily with code-first modeling. May use Onshape, Fusion, or SolidWorks.
-
-**What Maya Wants:**
-
-- See a real parametric model immediately.
-- Discover that sliders are parameters, not magic UI state.
-- Find the coordinate system and modeling conventions when she needs them.
-- Avoid feeling that she must read API docs before doing anything.
-
-**Ideal Flow:**
-
-```text
-Sign up -> Start Here project opens -> Width slider is visible -> change it -> model updates -> open Welcome docs for "what next?"
-```
-
-**Current Friction:**
-
-- The editor has powerful panels, but the first screen does not explain the working loop.
-- The file list does not provide a progression.
-- API docs are reference-first rather than first-session-first.
-
-### Sam - Software Engineer Evaluating ForgeCAD
-
-**Background:** Strong TypeScript/JavaScript developer, maybe less CAD knowledge. Wants to know if ForgeCAD fits automation and CI.
-
-**What Sam Wants:**
-
-- Confirm files are plain `.forge.js`.
-- Learn the local workflow and sync model.
-- Know how web projects relate to CLI projects.
-- See commands that can be pasted into a terminal.
-
-**Ideal Flow:**
-
-```bash
-forgecad project clone start-here
-forgecad run 01-parametric-bracket.forge.js
-forgecad render 3d 01-parametric-bracket.forge.js
-forgecad project push
-```
-
-**Current Friction:**
-
-- Hosted app and CLI feel like separate products.
-- GitHub/Google accounts need API tokens for CLI login, but that reason is not in the first-run path.
-- Project clone/push/pull is documented, but not introduced at the moment of motivation.
-
-### Priya - Robotics / Assembly Explorer
-
-**Background:** Interested in mechanisms, robotics, SDF/URDF, and multi-part assemblies. She needs a signal that ForgeCAD is more than boxes.
-
-**What Priya Wants:**
-
-- See multiple files or at least multiple model styles quickly.
-- Discover assemblies, joints/connectors, and exports.
-- Understand where the larger examples live without being dropped into all of them.
-
-**Ideal Flow:**
-
-```text
-Open Start Here -> inspect assembly starter -> follow docs to Assembly -> later browse examples/mechanical
-```
-
-**Current Friction:**
-
-- The first account project does not show the product's range.
-- The examples corpus is broad, but not curated into a first-session sequence.
-
-## Design Principles
-
-1. **The first screen should contain intent.** A code box with no project story makes ForgeCAD feel like a compiler, not a tool.
-2. **Curate before catalog.** First-run should show three chosen files, not every example.
-3. **Teach the loop, not the whole product.** The first session is edit -> run -> inspect -> move local.
-4. **The CLI is the serious workflow.** Hosted onboarding should point users toward local files, agents, validation, rendering, and project sync.
-5. **Docs should be layered.** Welcome first, CLI second, API reference only when the user has a concrete modeling question.
-6. **Do not point first-run users at package internals.** If examples are part of onboarding, they need a hosted docs/gallery surface, public repo link, or seeded project file the user can actually open.
-
-## Target Experience
-
-### Browser First Run
-
-When a hosted user with zero projects opens `/app`, ForgeCAD creates:
-
-```text
-Start Here/
-  00-start-here.forge.js
-  01-parametric-bracket.forge.js
-  02-assembly-basics.forge.js
-```
-
-The first file is active. It should be short, runnable, and friendly inside the code itself. The user can change dimensions and immediately see the model update.
-
-### Docs Welcome Page
-
-`/docs/welcome` is the public first-session docs page. It should answer:
-
-- What am I looking at?
-- What should I try first?
-- How do I move this project to the CLI?
-- How do I use an AI coding agent with ForgeCAD?
-- Where do I go after the first 10 minutes?
-
-### CLI Bridge
-
-The Welcome page and starter file both point to this path:
-
-```bash
-npm install -g forgecad
-forgecad login
-forgecad project clone start-here
-cd start-here
-forgecad studio .
-```
-
-For GitHub/Google accounts, choose API token during `forgecad login`. API tokens are available from Settings > API Tokens.
-
-## Friction to Experiment Map
-
-| Friction | Profiles affected | Experiment | Priority |
-|---|---|---|---|
-| New account opens an empty project | Alex, Maya, Sam, Priya | Create `Start Here` starter project when an account has zero projects | P0 |
-| Docs are reference-first | Alex, Maya, Sam | Add `/docs/welcome` before API sections | P0 |
-| CLI is not introduced at the moment of need | Alex, Sam | Put clone/studio/run commands in starter file and Welcome page | P0 |
-| Full examples are too broad for first contact | Maya, Priya | Curate three starter files instead of opening examples project | P0 |
-| AI-agent workflow is disconnected | Alex, Sam | Welcome page points to `forgecad skill install` and CLI validation loop | P1 |
-| No first-run instrumentation | All | Add analytics/audit event for starter project creation and first CLI token creation | P1 |
-
-## Implementation Map
-
-### Source-of-Truth Surfaces
-
-| Surface | Role | Owner |
-|---|---|---|
-| `docs/permanent/product/onboarding-first-experience.md` | Product source of truth | Product/engineering |
-| `docs/permanent/welcome.md` | User-facing Welcome docs page | Product/engineering |
-| `server/onboarding/starterProject.ts` | Starter project file template | Engineering |
-| `src/pages/DocsPage.tsx` | Docs navigation and route registration | Engineering |
-| `src/App.tsx` and `src/fs/HostedStudioProvider.ts` | Zero-project redirect/create behavior | Engineering |
-
-### First Implementation
-
-1. Add a `starter` project template option to `POST /api/projects`.
-2. Keep normal "New Project" behavior blank by default.
-3. Use `template: "starter"` only when the hosted app detects a user with zero projects.
-4. Add starter files server-side so the first project works even if the browser reloads immediately.
-5. Add `/docs/welcome` to the docs nav and search index.
-
-### Local Preview Note
-
-`npm run dev:studio` starts the hosted frontend only. It can show `/docs/welcome`, but it cannot create the hosted `Start Here` project unless the Fastify backend and Postgres are also running. To test starter project creation locally, run the hosted backend stack and open `/app` with a fresh account or empty project list.
-
-### Later Improvements
-
-- Add a first-run modal only if the starter project and docs page are not enough.
-- Add a hosted examples gallery later, separate from first-run. Until then, link to public repo examples instead of npm package paths.
-- Add "Clone locally" and "Create API token" affordances in the editor toolbar once the base path is proven.
-- Add first-run metrics: starter project created, first file opened, first save, first CLI token created, first project clone.
-
-## Non-Goals
-
-- Do not design a full tutorials system yet.
-- Do not open the entire examples project for new hosted accounts.
-- Do not add gamified checklists or badges.
-- Do not require the CLI before the browser gives immediate value.
-- Do not restore implicit local studio examples; `forgecad studio ./examples` should be explicit and `forgecad studio` without a project path should fail.
-
-## Risks and Mitigations
-
-| Risk | Mitigation |
-|---|---|
-| Starter files become stale as APIs evolve | Treat starter files like examples and run them through smoke checks. |
-| Users think the browser is the whole product | Put CLI path in the starter file and Welcome page. |
-| Users who want blank projects dislike seeded files | Only seed the first zero-project account path. Manual New Project stays blank. |
-| Docs page becomes too broad | Keep Welcome short and route API details to existing docs sections. |
-| Starter project creation fails | Fall back to the existing project path, but log/audit failures once observability is added. |
-
-## Validation
-
-The first implementation is good enough when:
-
-- A new hosted account with zero projects opens `/app` and lands in `Start Here`.
-- The project contains exactly the curated starter files.
-- The active file is `00-start-here.forge.js`.
-- `/docs/welcome` appears before API Reference in the docs sidebar and index.
-- The Welcome page includes the CLI login/token/project clone path.
-- The Welcome page does not tell users to browse npm package internals for examples.
-- Existing manual project creation still creates blank projects.
-
-## Experiment Log
-
-| Date | Change | Result |
-|---|---|---|
-| 2026-04-29 | Created this source-of-truth document and planned the P0 first-run path. | Done |
-| 2026-04-29 | Added `/docs/welcome` and wired zero-project hosted accounts to a server-side `Start Here` starter template. | Done |

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

@@ -1,17 +0,0 @@
-# Product Loop
-
-ForgeCAD's core product loop is:
-
-```text
-user goal -> AI edits .forge.js -> run -> render or inspect -> fix -> sweep params -> export or publish
-```
-
-This loop is the product. The editor, CLI, docs, hosted projects, skills, examples, exports, and inspection bundles should all make this loop faster and more trustworthy.
-
-The loop matters because AI will be wrong. The product promise is not that an agent invents perfect CAD on the first try. The promise is that the agent works inside a system that catches syntax errors, missing imports, invalid geometry, bad parameter ranges, collisions, thin walls, broken assembly relationships, and export failures.
-
-For a normal user, this turns CAD from expert hand work into guided iteration. They can describe the object, inspect a render, change a parameter, reject an awkward result, and ask for a fix. For a technical user, the loop is also automation-friendly: files are plain source, outputs are deterministic enough to compare, and checks can run from the terminal.
-
-Every product investment should be measured against this loop. A feature that looks impressive but cannot be validated, edited, parameterized, exported, or explained by the agent is weaker than a boring feature that closes the loop for a real manufacturing job.
-
-The strongest future product surface will combine natural language, editable code, visual evidence, manufacturing constraints, and project history. The user should feel that the AI is doing the hard modeling work, while ForgeCAD is keeping the work understandable and grounded.

package/dist/docs-raw/product/strategic-decisions.md

@@ -1,22 +0,0 @@
-# Strategic Decisions
-
-ForgeCAD product decisions should start from the same question: does this make AI-authored physical design more reliable, useful, and commercially valuable?
-
-A strong product bet usually has five properties. It serves a clear user segment. It gives the AI better domain vocabulary. It creates validation evidence. It connects to a real output route. It strengthens a business path such as Pro usage, embedded commerce, OEM partnership, or enterprise pilot work.
-
-This means not every geometry feature deserves product priority. A kernel capability is not automatically a product feature. A product feature exists when it helps a user get a job done, helps an agent express intent, or helps the business own a valuable workflow.
-
-For example, CNC primitives should be judged by the manufacturing workflow they unlock. If they only add shapes, they are weak. If they let an agent express pockets, contours, drilling, stock, tool access, material constraints, and validation around a real CNC route, they may be strategically important.
-
-Similarly, better API docs are useful but are not always the product answer. If the same workaround appears repeatedly, the deeper issue may be missing product vocabulary. Documentation should make the product easier to use; it should not hide the absence of a first-class concept.
-
-Use this filter for new ideas:
-
-- Who is the first user who will care?
-- What object or workflow becomes possible that was hard before?
-- What does the AI no longer have to improvise?
-- What can ForgeCAD validate or inspect?
-- What output, partner, or revenue path does it strengthen?
-- What would make this feature obviously successful after one month?
-
-If those answers are weak, keep the idea as research. If they are strong, the product likely has a real direction to explore.

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.