Frontsmith v1.0 is an open-source Codex-native front-office kit for local service businesses.
It gives an operator a single Codex-ready workspace to set up a local service business once, then keep operating the digital front office: ongoing customer inquiries, reply drafts, follow-ups, estimates, proposals, website updates, launch checks, activity history, and approval-gated connections.
The operator works through Codex: update the business details, review the Owner Brief, prepare customer replies and estimates, inspect the website and customer-facing drafts, approve what is ready, and keep improving the front office as the business changes.
Frontsmith's primary interface is chat-driven inside Codex, backed by repo files and local scripts. The expected loop is:
owner prompt in Codex
-> Frontsmith reads local business records
-> Codex returns a formatted brief, draft, plan, or checklist
-> owner reviews the generated artifact
-> approved changes update files, website content, or connected action drafts
Hosted evaluator Control Panel:
Included Acme website:
AI-readable discovery:
- Walkthrough:
https://frontsmith.neurapath.ai/#walkthrough - Hosted summary:
https://frontsmith.neurapath.ai/llms.txt - NeuraPath route:
https://neurapath.ai/frontsmith - Relay first proof:
https://www.neurarelay.com/developers/first-proof?neura_source=frontsmith&neura_campaign=frontsmith_applied_proof&neura_surface=readme
Frontsmith is ready for developer, agency, and operator feedback.
The fastest useful test is:
git clone https://github.com/neurarelay/frontsmith.git
cd frontsmith
npm install
npm run check
npm run bootstrap -- --business-name "Acme" --website-url "https://acme.com"
npm run first-run:status
npm run owner:brief
npm run prepare:connected-action -- --action-type "email" --title "Send consultation follow-up" --target "Customer follow-up" --evidence "Owner-provided customer notes"Then open a GitHub issue with what happened:
- first-run feedback from a developer trying the repo;
- agency/operator feedback about whether this would fit a real local-service client;
- one narrow improvement that would make the kit easier to adopt.
Start here:
GitHub repo
-> open in Codex
-> set up the business workspace
-> operate customer communications
-> review the Owner Brief
-> customize the included website
-> prepare estimates and proposals
-> preview locally
-> review the hosted Control Panel when needed
-> connect integrations when approved
-> deploy the approved website
-> keep operating through Codex workflows
Frontsmith keeps operating data separate from the public website: use .frontsmith/business/ for private business records and website/ for the launchable site.
The frontsmith.neurapath.ai target opens as a hosted Frontsmith Control Panel for Acme. It includes the Acme website at /website as the customer-facing site inside the wider front-office flow.
The hosted Control Panel is an evaluator preview of the Codex-native workflow, not the operating interface itself. It helps a cold visitor understand what they will actually see in Codex: prompts, Frontsmith responses, generated Markdown artifacts, local file updates, previews, and owner approval before live action.
Frontsmith v1.0 includes the essential digital front office for a local service business:
- Business Setup
- Owner Brief
- Website
- Customer Desk
- Ongoing customer communication
- Estimates and Proposals
- Activity Log
- Settings and Integrations
- Extension Planning
Open this repository in Codex and start with:
Set up Frontsmith for my local service business.
Codex will set up a local business workspace, prepare the Owner Brief, update the included website, and start the ongoing front-office loop: customer reply drafts, follow-up notes, estimate and proposal drafts, launch checks, and approval-gated connection steps for publishing, email, file storage, and scheduling tools.
For a real business replacing the Acme defaults, ask Codex to run:
npm run first-run:statusThis writes .frontsmith/business/launch/first-run-readiness.md, showing which business profile fields are customized, which still look like placeholders, which workspace files exist, and what remains owner-approval-gated before launch.
The Owner Brief is Frontsmith's current-state view for one business. It summarizes what changed, what is waiting, what is blocked, what needs approval, and what the owner should do next.
The Customer Desk is the ongoing communication lane. It keeps customer requests, reply drafts, follow-up notes, estimate next steps, and owner approvals together after the website is launched.
Connection and deployment steps stay approval-gated. Frontsmith prepares the path; it does not connect accounts, publish the site, or send customer messages without explicit owner approval.
The Codex workflow walkthrough proof is available at docs/walkthroughs/codex-workflow-proof.md. It shows the Owner Brief, Customer Desk reply draft, estimate preparation, website update/preview, extension planning, connected-action receipt, generated files, preview links, and approval boundaries.
The Frontsmith Relay proof map is available at docs/product/relay-proof-map.md. It maps Customer Desk replies, estimates, website updates, launch status, extension planning, and connected-action receipts to the authority-before-action boundary that Neura Relay governs in connected client mode.
For proposed live actions, Frontsmith can prepare a dry-run connected-action receipt before any adapter runs:
npm run prepare:connected-action -- --action-type "email" --title "Send consultation follow-up" --target "Customer follow-up" --evidence "Owner-provided customer notes"This writes .frontsmith/business/connected-actions/... Markdown and JSON records with the proposed action, approval gate, Neura Registry/Relay reference placeholders, blocked adapters, and no-live-action safety boundary.
Frontsmith already includes the launchable website here:
website/
This is a static website folder, not a Next.js app. website/ is the business website source: HTML, CSS, JavaScript, favicon files, logo files, and any future local image assets belong there.
During setup, Codex applies the business name, website URL, core services, contact details, branding, images, and search/social metadata to that single-page website. Changing the business name updates the business profile and website content; the website folder stays stable.
The default photos currently come from the business profile's media URLs. A business can replace them with local files under website/assets/ and point the media fields to /assets/... paths.
The hosted Frontsmith Control Panel uses demo/ as its entry point and copies website/ into the built demo at /website.
Operators can let Codex run the commands. Developers can run them directly:
npm run check
npm run bootstrap -- --business-name "Acme" --website-url "https://acme.com"
npm run owner:brief
npm run prepare:reply -- --name "Customer" --project "Kitchen Remodeling" --notes "Customer wants help planning the next step."
npm run prepare:estimate -- --project "Kitchen Remodeling" --scope "Cabinets, counters, lighting, and layout clarification."
npm run prepare:extension -- --capability "Consultation scheduling" --connector "Google Calendar" --goal "Prepare an owner-reviewed workflow for approved consultation requests."
npm run prepare:connected-action -- --action-type "email" --title "Send consultation follow-up" --target "Customer follow-up" --evidence "Owner-provided customer notes"
npm run first-run:status
npm run update:website
npm run launch:status
npm run build:demo
npm run preview:demo
npm run deploy:check
npm run preview:websiteThe root vercel.json keeps Vercel in static-site mode and builds the hosted Frontsmith Control Panel into dist/frontsmith-demo. Frontsmith does not require next.config, src/app, or a Next.js build for the hosted target.
npm run deploy:check is a preflight gate, not a deployment command. It verifies the demo build, included website, Vercel static-site configuration, clean URLs, SEO/social metadata, icons, referenced assets, contact form API wiring, and required production email-delivery environment variables. It exits with blockers until the Resend and contact variables are configured, and it never sends email or deploys the site.
Pull requests and pushes to main run the GitHub Actions launch gate in .github/workflows/launch-gate.yml.
The launch gate installs Node.js 20 dependencies, runs npm run check, builds the hosted demo with npm run build:demo, and runs npm test.
npm run deploy:check remains a local/manual preflight because it intentionally verifies production contact-delivery configuration. It should run only when safe placeholder environment variables or the approved business-owned delivery variables are available. The GitHub Actions gate does not deploy, send email, change DNS, call providers, or execute customer-facing actions.
The website contact form posts to:
/api/contact
That server-side function sends the project request through Resend when delivery is configured. Browser JavaScript handles validation and the success state, but the email provider key stays in Vercel environment variables and is never exposed to the public website.
The default ownership model is business-owned email delivery: each business uses its own Resend account, verified sending domain, API key, and Vercel environment variables. NeuraPath-managed delivery can be offered later as a managed setup tier, but it is not the open-source default.
Required production variables:
CONTACT_DELIVERY_MODE=resend
CONTACT_TO_EMAIL=projects@acme.com
CONTACT_FROM_EMAIL="Acme <hello@acme.com>"
CONTACT_SUBJECT_PREFIX=Website project request
FRONTSMITH_TENANT_ID=acme
RESEND_API_KEY=re_xxxxxxxxx
If /api/contact is not configured, the browser falls back to a prefilled email draft through the business email address.
Useful daily front-office commands:
npm run prepare:reply -- --name "Customer" --project "Kitchen Remodeling" --notes "Customer wants help planning the next step."
npm run prepare:estimate -- --project "Kitchen Remodeling" --scope "Cabinets, counters, lighting, and layout clarification."
npm run prepare:extension -- --capability "Consultation scheduling" --connector "Google Calendar" --goal "Prepare an owner-reviewed workflow for approved consultation requests."
npm run prepare:connected-action -- --action-type "calendar" --title "Create consultation hold" --target "Approved consultation request" --evidence "Owner-approved scheduling notes"
npm run owner:brief
npm run deploy:check
npm testOperator path
docs/operator/start-here.md first-run guidance for business operators
workflows/ Codex runbooks for setup, website, replies, estimates, and launch
.frontsmith/business/ local business workspace created on first run, gitignored
Owner Brief current-state summary prepared from local records
website/ launchable website that gets customized and deployed
demo/ hosted Frontsmith Control Panel for frontsmith.neurapath.ai
Product and development
AGENTS.md Codex operating rules for this repository
frontsmith.config.json v1.0 kit configuration
blueprints/local-service/ default local service business blueprint
docs/product/architecture.md product architecture and data flow
docs/product/package-spec.md v1.0 package scope
docs/developer/extension-guide.md extension guidance for developers
DEVELOPERS.md developer rules
scripts/ local bootstrap, website updates, front-office tools, extension plans, preview, demo build, and checks
tests/ launch readiness and regression tests for the promised workflows
docs/assets/ README screenshots
packages/core/ shared business workspace model
packages/adapters/ integration adapter boundary
packages/neura/ governed-action boundary
Frontsmith prepares, drafts, previews, and exports by default.
It does not silently send emails, publish websites, change DNS, contact customers, submit provider updates, or execute customer-facing actions. Consequential actions require explicit owner approval. In connected client mode, those actions should pass through Neura Registry and Neura Relay before execution.