[{"data":1,"prerenderedAt":31},["ShallowReactive",2],{"doc-development":3},{"html":4,"headings":5},"\u003Cp>How to run HelpBites from source, find your way around, change it safely and get a change merged. HelpBites is in\npublic beta and moves quickly: \u003Ccode>main\u003C\u002Fcode> is always releasable, and \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Felrumo\u002Fhelp-bites-oss\u002Fblob\u002Fmain\u002FCHANGELOG.md\" target=\"_blank\" rel=\"noopener\">CHANGELOG.md\u003C\u002Fa> is the history.\nRead \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Felrumo\u002Fhelp-bites-oss\u002Fblob\u002Fmain\u002FCONTRIBUTING.md\" target=\"_blank\" rel=\"noopener\">CONTRIBUTING.md\u003C\u002Fa> (licenses, the CLA, the rules of the road) before your first pull request.\u003C\u002Fp>\n\u003Ch2 id=\"what-you-need\">What you need\u003Ca class=\"heading-anchor\" href=\"#what-you-need\" aria-label=\"Link to this section\">#\u003C\u002Fa>\u003C\u002Fh2>\n\u003Cul>\n\u003Cli>\u003Ca href=\"https:\u002F\u002Fbun.sh\" target=\"_blank\" rel=\"noopener\">Bun\u003C\u002Fa> 1.x. It is the package manager, the script runner, the test runner and the production runtime.\u003C\u002Fli>\n\u003Cli>Docker with the Compose plugin, for MongoDB, Parse, Redis, Meilisearch and the bucket.\u003C\u002Fli>\n\u003Cli>Optional: Xcode 16 and \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fyonaskolb\u002FXcodeGen\" target=\"_blank\" rel=\"noopener\">XcodeGen\u003C\u002Fa> for the native app.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Ch2 id=\"run-it\">Run it\u003Ca class=\"heading-anchor\" href=\"#run-it\" aria-label=\"Link to this section\">#\u003C\u002Fa>\u003C\u002Fh2>\n\u003Cdiv class=\"code-block\">\u003Cbutton type=\"button\" class=\"copy-btn\" data-copy aria-label=\"Copy to clipboard\">Copy\u003C\u002Fbutton>\u003Cpre class=\"shj-lang-bash\">\u003Ccode>\u003Cspan class=\"shj-syn-func\">git\u003C\u002Fspan> clone https:\u002F\u002Fgithub.com\u002Felrumo\u002Fhelp-bites-oss.git \u003Cspan class=\"shj-syn-kwd\">&#38;&#38;\u003C\u002Fspan> \u003Cspan class=\"shj-syn-func\">cd\u003C\u002Fspan> help-bites-oss\n\u003Cspan class=\"shj-syn-func\">cp\u003C\u002Fspan> .env.example .env                       \u003Cspan class=\"shj-syn-cmnt\"># the defaults already target the dev stack below\u003C\u002Fspan>\n\u003Cspan class=\"shj-syn-func\">docker\u003C\u002Fspan> compose\u003Cspan class=\"shj-syn-kwd\"> -f\u003C\u002Fspan> docker-compose.yml\u003Cspan class=\"shj-syn-kwd\"> -f\u003C\u002Fspan> docker-compose.dev.yml --profile dev \\\n  \u003Cspan class=\"shj-syn-func\">up\u003C\u002Fspan>\u003Cspan class=\"shj-syn-kwd\"> -d\u003C\u002Fspan> sb-mongo sb-parse sb-redis sb-meili sb-rustfs\n\u003Cspan class=\"shj-syn-func\">bun\u003C\u002Fspan> \u003Cspan class=\"shj-syn-kwd\">install\u003C\u002Fspan>\n\u003Cspan class=\"shj-syn-func\">bun\u003C\u002Fspan> run schema:apply                       \u003Cspan class=\"shj-syn-cmnt\"># Parse classes, permissions, indexes (idempotent)\u003C\u002Fspan>\n\u003Cspan class=\"shj-syn-func\">bun\u003C\u002Fspan> run search:setup                       \u003Cspan class=\"shj-syn-cmnt\"># Meilisearch indexes and settings (idempotent)\u003C\u002Fspan>\n\u003Cspan class=\"shj-syn-func\">bun\u003C\u002Fspan> run dev                                \u003Cspan class=\"shj-syn-cmnt\"># http:\u002F\u002Flocalhost:3100\u003C\u002Fspan>\u003C\u002Fcode>\u003C\u002Fpre>\u003C\u002Fdiv>\n\u003Cp>The first visit asks you to create the operator account. The dev overlay publishes the services on localhost: Parse\n\u003Ccode>:1337\u003C\u002Fcode> (dashboard \u003Ccode>:4040\u003C\u002Fcode>, login \u003Ccode>admin\u003C\u002Fcode>\u002F\u003Ccode>admin\u003C\u002Fcode>), Redis \u003Ccode>:6379\u003C\u002Fcode>, Meilisearch \u003Ccode>:7700\u003C\u002Fcode>, RustFS \u003Ccode>:9000\u003C\u002Fcode>\u002F\u003Ccode>:9001\u003C\u002Fcode>. It is only\nfor development, never for production.\u003C\u002Fp>\n\u003Cp>Useful extras:\u003C\u002Fp>\n\u003Cdiv class=\"code-block\">\u003Cbutton type=\"button\" class=\"copy-btn\" data-copy aria-label=\"Copy to clipboard\">Copy\u003C\u002Fbutton>\u003Cpre class=\"shj-lang-bash\">\u003Ccode>\u003Cspan class=\"shj-syn-func\">bun\u003C\u002Fspan> run seed:knowledge                     \u003Cspan class=\"shj-syn-cmnt\"># a demo knowledge model (against the running app)\u003C\u002Fspan>\n\u003Cspan class=\"shj-syn-func\">bun\u003C\u002Fspan> scripts\u002Fdev-token.mjs \u003Cspan class=\"shj-syn-oper\">&lt;\u003C\u002Fspan>projectId\u003Cspan class=\"shj-syn-oper\">&gt;\u003C\u002Fspan> \u003Cspan class=\"shj-syn-oper\">&lt;\u003C\u002Fspan>userId\u003Cspan class=\"shj-syn-oper\">&gt;\u003C\u002Fspan> \u003Cspan class=\"shj-syn-str\">\"Demo user\"\u003C\u002Fspan> demo@example.com   \u003Cspan class=\"shj-syn-cmnt\"># an identity token, no host code\u003C\u002Fspan>\n\u003Cspan class=\"shj-syn-func\">bun\u003C\u002Fspan> run reindex                            \u003Cspan class=\"shj-syn-cmnt\"># rebuild the search index\u003C\u002Fspan>\n\u003Cspan class=\"shj-syn-func\">bun\u003C\u002Fspan> run add-agent                          \u003Cspan class=\"shj-syn-cmnt\"># another operator, from the CLI\u003C\u002Fspan>\u003C\u002Fcode>\u003C\u002Fpre>\u003C\u002Fdiv>\n\u003Cp>\u003Ccode>\u002Fdemo\u003C\u002Fcode> serves the panel against canned data with no backend (\u003Ccode>app\u002Futils\u002FdemoApi.ts\u003C\u002Fcode>): the quickest way to check a UI\nchange. The API reference is at \u003Ccode>\u002F_docs\u002Fscalar\u003C\u002Fcode>; your own AI, email and GitHub setups are in \u003Ca href=\"\u002Fdocs\u002Fsetup\">Setting things up\u003C\u002Fa>.\u003C\u002Fp>\n\u003Cp>To run the real image instead, from your checkout: \u003Ccode>docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build\u003C\u002Fcode>.\u003C\u002Fp>\n\u003Ch2 id=\"checks\">Checks\u003Ca class=\"heading-anchor\" href=\"#checks\" aria-label=\"Link to this section\">#\u003C\u002Fa>\u003C\u002Fh2>\n\u003Cdiv class=\"table-wrap\">\u003Ctable>\n\u003Cthead>\n\u003Ctr>\n\u003Cth>\u003C\u002Fth>\n\u003Cth>What\u003C\u002Fth>\n\u003Cth>When\u003C\u002Fth>\n\u003C\u002Ftr>\n\u003C\u002Fthead>\n\u003Ctbody>\n\u003Ctr>\n\u003Ctd>\u003Ccode>bun test\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Unit tests, the features map, the tenancy guard, the edition boundary, the native parity tests. No services needed apart from an optional Redis (\u003Ccode>REDIS_TEST_URL\u003C\u002Fcode>) for the usage counters\u003C\u002Ftd>\n\u003Ctd>Before every push\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>bun run smoke\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>End to end against the running stack\u003C\u002Ftd>\n\u003Ctd>After changing a flow\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>bun run smoke:isolation\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>One workspace can never reach another's data\u003C\u002Ftd>\n\u003Ctd>Whenever you touch an admin route\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>bun run build\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The production build\u003C\u002Ftd>\n\u003Ctd>Before a release; CI does it on every PR\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>bun scripts\u002Fcheck-edition-build.mjs community\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The build holds no \u003Ccode>ee\u002F\u003C\u002Fcode> code\u003C\u002Ftd>\n\u003Ctd>CI does it\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftbody>\n\u003C\u002Ftable>\u003C\u002Fdiv>\n\u003Cp>CI (\u003Ccode>.github\u002Fworkflows\u002Fci.yml\u003C\u002Fcode>) runs the tests and the build on every pull request.\u003C\u002Fp>\n\u003Ch2 id=\"the-layout\">The layout\u003Ca class=\"heading-anchor\" href=\"#the-layout\" aria-label=\"Link to this section\">#\u003C\u002Fa>\u003C\u002Fh2>\n\u003Cdiv class=\"code-block\">\u003Cbutton type=\"button\" class=\"copy-btn\" data-copy aria-label=\"Copy to clipboard\">Copy\u003C\u002Fbutton>\u003Cpre class=\"shj-lang-plain\">\u003Ccode>app\u002F                      the Nuxt panel and the public pages (landing, docs, embeds)\n  pages\u002F                  routes; project sections are listed in app\u002Futils\u002FprojectSections.ts\n  components\u002F             UI; app\u002Fcomponents\u002Fsettings holds the settings tabs\n  utils\u002FdemoApi.ts        canned data behind \u002Fdemo\nserver\u002F\n  routes\u002Fv1\u002F**            the API, one file per route, each with defineRouteMeta({ openAPI })\n  utils\u002F                  the logic: tenancy, auth, conversations, email, AI gateway, MCP tools\n  plugins\u002F                boot-time checks and schedulers\nshared\u002F                   TypeScript that the server and the panel share; ported by hand to Swift\npublic\u002F*.js               the drop-in scripts host sites include (MIT): widget.js, feedback.js, changelog.js …\ncli\u002F                      `helpbites changelog` (MIT)\nhelpbites-native\u002F         the SwiftUI iPhone, iPad and Mac app\nscripts\u002F                  schema, search, migrations, seeding, smoke tests\ndocs\u002F                     these guides; shared\u002Fdocs.ts picks which ones publish at \u002Fdocs\ni18n\u002Flocales\u002F             en (required, the fallback), ca, es, ja, ko, zh\nfeatures.json             the machine-readable map of what the product does\nee\u002F                       the hosted service's commercial layer. Not in this repository\u003C\u002Fcode>\u003C\u002Fpre>\u003C\u002Fdiv>\n\u003Cp>Three things worth knowing early:\u003C\u002Fp>\n\u003Cul>\n\u003Cli>\u003Cstrong>Parse is the database layer.\u003C\u002Fstrong> Data lives in MongoDB behind Parse Server; \u003Ccode>scripts\u002Fensure-schema.mjs\u003C\u002Fcode> declares every\nclass, permission and index and is safe to run any time. A schema change is a change to that file and a line in the\nchangelog.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Everything is workspace-scoped.\u003C\u002Fstrong> A \u003Cem>workspace\u003C\u002Fem> owns \u003Cem>projects\u003C\u002Fem>. Admin routes go through \u003Ccode>requireMember\u003C\u002Fcode> \u002F\n\u003Ccode>requireProject\u003C\u002Fcode> and the \u003Ccode>scoped.*\u003C\u002Fcode> getters in \u003Ccode>server\u002Futils\u002Ftenancy.ts\u003C\u002Fcode>; \u003Ccode>tests\u002Ftenancy.guard.test.ts\u003C\u002Fcode> fails the build\non a route that does not.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Two editions, one codebase.\u003C\u002Fstrong> Community is everything here, unlimited. Cloud adds sign-up, plans and billing from a\nprivate layer through the seams in \u003Ccode>server\u002Futils\u002Fedition.ts\u003C\u002Fcode> and \u003Ccode>app\u002Futils\u002FeditionUi.ts\u003C\u002Fcode>. Core never imports from\n\u003Ccode>ee\u002F\u003C\u002Fcode> (\u003Ca href=\"https:\u002F\u002Fgithub.com\u002Felrumo\u002Fhelp-bites-oss\u002Fblob\u002Fmain\u002Fdocs\u002FEDITIONS.md\" target=\"_blank\" rel=\"noopener\">Editions\u003C\u002Fa>).\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Ch2 id=\"adding-a-feature\">Adding a feature\u003Ca class=\"heading-anchor\" href=\"#adding-a-feature\" aria-label=\"Link to this section\">#\u003C\u002Fa>\u003C\u002Fh2>\n\u003Cp>\u003Ca href=\"https:\u002F\u002Fgithub.com\u002Felrumo\u002Fhelp-bites-oss\u002Fblob\u002Fmain\u002FCLAUDE.md\" target=\"_blank\" rel=\"noopener\">CLAUDE.md\u003C\u002Fa> is the checklist, and it applies to people as much as to coding assistants. In short, a\nfeature is done when it has:\u003C\u002Fp>\n\u003Col>\n\u003Cli>\u003Cstrong>An edition decision\u003C\u002Fstrong> (community and cloud by default), written into \u003Ccode>features.json\u003C\u002Fcode>.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Web and native\u003C\u002Fstrong>: a page under \u003Ccode>app\u002Fpages\u002F\u003C\u002Fcode> and a screen under \u003Ccode>helpbites-native\u002FApp\u002FFeatures\u002F&lt;Area&gt;\u002F\u003C\u002Fcode>, or the gap\nwritten down in \u003Ccode>features.json\u003C\u002Fcode> (\u003Ccode>notBuilt\u003C\u002Fcode>) and \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Felrumo\u002Fhelp-bites-oss\u002Fblob\u002Fmain\u002Fdocs\u002FFEATURES.md\" target=\"_blank\" rel=\"noopener\">FEATURES.md\u003C\u002Fa> §14. Anything both need goes in \u003Ccode>shared\u002F\u003C\u002Fcode>,\nwith a parity test where Swift copies constants (see \u003Ccode>tests\u002FemailNativeParity.test.ts\u003C\u002Fcode>).\u003C\u002Fli>\n\u003Cli>\u003Cstrong>An API\u003C\u002Fstrong>: routes under \u003Ccode>server\u002Froutes\u002Fv1\u002F**\u003C\u002Fcode> with OpenAPI metadata, accepting an operator session or an \u003Ccode>ak_\u003C\u002Fcode> key, and\nan MCP tool in \u003Ccode>server\u002Futils\u002Fmcp\u002Ftools.ts\u003C\u002Fcode> plus a row in \u003Ca href=\"\u002Fdocs\u002Fmcp\">MCP.md\u003C\u002Fa> (\u003Ccode>tests\u002FmcpCoverage.test.ts\u003C\u002Fcode> checks).\u003C\u002Fli>\n\u003Cli>\u003Cstrong>A guide\u003C\u002Fstrong> in \u003Ccode>docs\u002F\u003C\u002Fcode> (add it to \u003Ccode>shared\u002Fdocs.ts\u003C\u002Fcode> to publish it), with curl examples, and for anything end users see a\ndrop-in \u003Ccode>&lt;script&gt;\u003C\u002Fcode> in \u003Ccode>public\u002F\u003C\u002Fcode> and a Swift snippet.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Strings\u003C\u002Fstrong> through \u003Ccode>$t()\u003C\u002Fcode> in \u003Ccode>i18n\u002Flocales\u002Fen.json\u003C\u002Fcode> (add the other five when you can).\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Its entry in \u003Ccode>features.json\u003C\u002Fcode>\u003C\u002Fstrong>, \u003Ccode>docs\u002FFEATURES.md\u003C\u002Fcode>, a line under \u003Cem>Unreleased\u003C\u002Fem> in \u003Ccode>CHANGELOG.md\u003C\u002Fcode>, and a decision on the\nlanding page (\u003Ccode>landing.listed\u003C\u002Fcode>; the page and its \u003Ccode>landing.*\u003C\u002Fcode> words are in the cloud repo).\u003C\u002Fli>\n\u003C\u002Fol>\n\u003Cp>\u003Ccode>tests\u002Ffeatures.test.ts\u003C\u002Fcode> fails when \u003Ccode>features.json\u003C\u002Fcode> names a file, route, doc or key that does not exist.\u003C\u002Fp>\n\u003Ch2 id=\"the-native-app\">The native app\u003Ca class=\"heading-anchor\" href=\"#the-native-app\" aria-label=\"Link to this section\">#\u003C\u002Fa>\u003C\u002Fh2>\n\u003Cp>\u003Ccode>helpbites-native\u002F\u003C\u002Fcode> is one SwiftUI target for iPhone, iPad and Mac (iOS 18, macOS 15), generated by XcodeGen.\u003C\u002Fp>\n\u003Cdiv class=\"code-block\">\u003Cbutton type=\"button\" class=\"copy-btn\" data-copy aria-label=\"Copy to clipboard\">Copy\u003C\u002Fbutton>\u003Cpre class=\"shj-lang-bash\">\u003Ccode>\u003Cspan class=\"shj-syn-func\">cd\u003C\u002Fspan> helpbites-native\n\u003Cspan class=\"shj-syn-func\">xcodegen\u003C\u002Fspan> generate                          \u003Cspan class=\"shj-syn-cmnt\"># after adding or removing files\u003C\u002Fspan>\n\u003Cspan class=\"shj-syn-func\">open\u003C\u002Fspan> HelpBitesNative.xcodeproj\u003C\u002Fcode>\u003C\u002Fpre>\u003C\u002Fdiv>\n\u003Cp>Set \u003Ccode>APP_BASE_URL\u003C\u002Fcode> in \u003Ccode>Config\u002FDebug.xcconfig\u003C\u002Fcode> to your server (the simulator default is \u003Ccode>http:\u002F\u002Flocalhost:3100\u003C\u002Fcode>; a device\nneeds an HTTPS tunnel or your LAN address) and your team in \u003Ccode>project.yml\u003C\u002Fcode>, then run the \u003Ccode>HelpBitesNative\u003C\u002Fcode> scheme. The share\nextension needs the App Group \u003Ccode>group.com.helpbites.operator\u003C\u002Fcode> on both targets. The app's version is \u003Ccode>MARKETING_VERSION\u003C\u002Fcode> in\n\u003Ccode>project.yml\u003C\u002Fcode>, kept equal to \u003Ccode>package.json\u003C\u002Fcode> by a test. More in \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Felrumo\u002Fhelp-bites-oss\u002Fblob\u002Fmain\u002Fhelpbites-native\u002FREADME.md\" target=\"_blank\" rel=\"noopener\">helpbites-native\u002FREADME.md\u003C\u002Fa>.\u003C\u002Fp>\n\u003Ch2 id=\"conventions\">Conventions\u003Ca class=\"heading-anchor\" href=\"#conventions\" aria-label=\"Link to this section\">#\u003C\u002Fa>\u003C\u002Fh2>\n\u003Cul>\n\u003Cli>Match the surrounding code: comment density, naming, idiom. No new dependency for something a few lines can do.\u003C\u002Fli>\n\u003Cli>Comments say why, not what. Tests sit in \u003Ccode>tests\u002F\u003C\u002Fcode> and are named for what they protect.\u003C\u002Fli>\n\u003Cli>Public scripts (\u003Ccode>public\u002F*.js\u003C\u002Fcode>) have no dependencies and start with the SPDX header; they must work from one tag with\nonly \u003Ccode>data-project=&quot;pk_…&quot;\u003C\u002Fcode>.\u003C\u002Fli>\n\u003Cli>Errors are \u003Ccode>createError({ statusCode, statusMessage })\u003C\u002Fcode> with a message a person can act on.\u003C\u002Fli>\n\u003Cli>Pull requests are small and say what and why. The template asks for \u003Ccode>bun test\u003C\u002Fcode>, workspace scoping and the CLA.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Ch2 id=\"releasing\">Releasing\u003Ca class=\"heading-anchor\" href=\"#releasing\" aria-label=\"Link to this section\">#\u003C\u002Fa>\u003C\u002Fh2>\n\u003Cp>Maintainers: \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Felrumo\u002Fhelp-bites-oss\u002Fblob\u002Fmain\u002Fdocs\u002FRELEASING.md\" target=\"_blank\" rel=\"noopener\">RELEASING.md\u003C\u002Fa> covers the version, the tag, Docker Hub and the public changelog.\u003C\u002Fp>\n",[6,10,13,16,19,22,25,28],{"id":7,"text":8,"level":9},"what-you-need","What you need",2,{"id":11,"text":12,"level":9},"run-it","Run it",{"id":14,"text":15,"level":9},"checks","Checks",{"id":17,"text":18,"level":9},"the-layout","The layout",{"id":20,"text":21,"level":9},"adding-a-feature","Adding a feature",{"id":23,"text":24,"level":9},"the-native-app","The native app",{"id":26,"text":27,"level":9},"conventions","Conventions",{"id":29,"text":30,"level":9},"releasing","Releasing",1794596526304]