Welcome to Mentor, Cole

This is the short version of how we build Mentor together. It is written to be read on a phone.

Mentor turns someone's goal into a 12-week plan and checks in until they get there. Live app: https://mentor.arnao.ai

You are a product owner and a co-developer. That means two jobs: decide what is worth building (from real feedback), and build some of it yourself through pull requests.

1. Accounts you need

• GitHub. Send Byron your GitHub username. You will get a collaborator invite with write access (not admin). Branch rules apply to you exactly as to Byron.
• Mentor. Sign in at https://mentor.arnao.ai with the Google account you confirmed to Byron. He grants that account the product-owner role.
• Vercel (optional). Only needed if you want to pull preview environment values yourself. Otherwise Byron sends you a preview-only .env.local.

You do not need, and will never be given, any production key.

2. Get the code

git clone https://github.com/<from-your-invite>/mentor.git
cd mentor
npm install

The repo link arrives with your GitHub invite.

What is inside:

• index.html is the whole app (HTML, CSS and JavaScript in one file).
• api/*.js are the server functions.
• Storage is Vercel Blob. There is no build step.

3. Run it on your machine

npm i -g vercel
cp .env.example .env.local    # fill in the PREVIEW values Byron gives you
vercel dev

Then open http://localhost:3000

Use preview values only. Never production. The preview has its own empty storage and no AI key, SMS or email, so you cannot hurt a real user by testing. AI features show "not configured" there unless Byron adds a small preview key.

4. Your first pull request (keep it tiny)

Your first PR should be a copy fix: a typo, a clearer button label. The point is to walk the whole pipe once before anything big rides it.

1. Pick or open an issue. Note its number, say #12.
2. Make a branch: git checkout -b copy/12-button-label
3. Change the text in index.html.
4. Commit and push: git push -u origin copy/12-button-label
5. Open the PR on GitHub. Title: copy: clearer start button (#12). Put Fixes #12 in the body and fill in the template.
6. Wait for the three CI checks to go green (syntax, tests, secret scan).
7. Open the preview URL and check your change at phone width.
8. Merge to main yourself once CI is green (ask Byron for a look whenever you want one). Byron promotes main to production.
9. Byron promotes main to production. Your change is live at https://mentor.arnao.ai

5. What the preview URL is

Every PR gets its own temporary copy of the app on Vercel, deployed by a bot on Byron's server within about ten minutes of your push. The bot comments the link on the PR and sets a "mentor/preview" status; it looks like a long *.vercel.app address. No deploy secret lives in GitHub.

• It runs your branch's code.
• It uses a separate Blob store and a small separate AI key.
• It has no SMS, email or Telegram, and no production secrets.

main also has a stable "next" preview, so you can see what the next production release will contain.

6. Feedback: filing and triaging it

Everyone in the app has the feedback button (bottom corner, every screen). Kinds: Bug, Issue, Idea, Note. You can tap "Point at what you mean" to attach the exact element.

As a product owner, the same button also shows "On this page": every item filed on the screen you are looking at. From there you can:

• fix the text, kind, status or priority,
• promote an item: it becomes a backlog item and then a GitHub issue.

Two privacy rules:

• The public GitHub issue carries only the text you approve. Screen snapshots, pointed-at elements and the filer's email stay private in Mentor.
• Your reads of other people's feedback are logged, because snapshots contain real users' screen text.

When a promoted issue ships, the person who filed it is told automatically.

7. The evening text

At about 6 pm Eastern you get one SMS (three segments at most): today's new feedback, backlog changes, releases, open PRs, and the AI spend so far this month. It ends with a link to the Controller.

It always sends, even on a quiet day ("0 new · daemons healthy · $3.10 of $50"). If it does not arrive, something is broken, so tell Byron. Reply STOP to turn it off.

8. The $50 a month AI budget

The product loop (not the in-app AI users pay for with their own caps) has a hard limit of $50 a month. One ledger on Byron's Mac mini tracks it.

At 80% of any line the evening text warns you. At 100% that job steps down: a plain digest, no PR summary, and vision reviews wait for Byron.

The PR summary is advice, never a gate. CI and a human review are the gates.

9. Big changes (like social media in the API and MCP backends)

Your first big change is adding social media to Mentor's API and MCP backends. Big changes go like this:

1. Issue first. Open a "Vision review" issue: problem, users, data touched, cost, risks, rollout. A product owner adds the vision-review label.
2. One product-direction review. Fable writes it on the issue. Talk it through, adjust the design.
3. Build in api/. Provider calls (and any OAuth tokens) stay on the server. Keys come only from environment variables; add each name to .env.example. Reuse the existing per-user cost cap for any paid call.
4. Behind a flag, off by default. Ship in small PRs; each one is safe to merge even if the feature is not finished.
5. Byron reviews (it will touch sensitive files and costs), you both test it on the preview, then Byron promotes it.

The detailed checklist is in CONTRIBUTING.md under "Adding a backend integration".

10. The few hard rules

• Never commit a secret, a real email or a phone number. CI scans every PR.
• Never use production environment values, locally or in a preview.
• New features: behind a flag, off by default.
• Only main goes to production, and only Byron merges that.
• When in doubt, open an issue and ask.