Frequently Asked Questions
These answers come from the troubleshooting notes and documentation of each product. Each product also has its own troubleshooting page with more detail, linked at the end of its section.
General
Section titled “General”Which Operating Systems Are Supported?
Section titled “Which Operating Systems Are Supported?”AI Business OS, PRIMA Project Management, PRIMA Memory and PRIMA CRM are built and tested on macOS. They may run on Windows through WSL or Git Bash, but Windows is not directly supported, and no outcome is guaranteed on any operating system. The AI Business OS getting started guide sets up WSL on Windows, and only the update script has been tested under Git Bash. The PRIMA Scholar installer runs on macOS and Linux.
Do I Need a GitHub Account?
Section titled “Do I Need a GitHub Account?”You do not need one to install. Claude installs AI Business OS, PRIMA Project Management, PRIMA Memory and PRIMA CRM from git.genaiskills.io with the key in the email you receive when you buy. PRIMA Scholar is free and installs as a Claude Code plugin. To keep your workspace in step across machines, /sync and /night push to a remote git repository, so you need somewhere to hold that repository.
Can I Keep My Workspace in Dropbox, OneDrive, Google Drive or iCloud?
Section titled “Can I Keep My Workspace in Dropbox, OneDrive, Google Drive or iCloud?”Keep it outside those folders. A cloud sync service and git both lock and rewrite the files in .git/ without knowing about each other. The result can be lock errors, a corrupted index, lost commits, conflict copies inside .git/, or files iCloud has moved off your disk. Use git and your remote repository to move work between machines.
Which Products Need Which?
Section titled “Which Products Need Which?”AI Business OS needs nothing else. You install PRIMA Project Management, PRIMA Memory and PRIMA CRM into an AI Business OS workspace. The CRM needs the AI Business OS project register and does not need PRIMA Project Management. PRIMA Scholar stands alone, and How the Products Fit Together explains how the products depend on each other.
AI Business OS
Section titled “AI Business OS”Claude Does Not Recognise a Command
Section titled “Claude Does Not Recognise a Command”Check the spelling, because commands are case-sensitive, and check that the command exists in .claude/commands/. Type /help to see the commands available, or open the Command Reference, which lists every command the products ship.
An MCP Server Has Stopped Working
Section titled “An MCP Server Has Stopped Working”Restart VS Code completely. If the server signs in to an outside service, it may need you to sign in again on this machine.
Will an Update Overwrite My Changes?
Section titled “Will an Update Overwrite My Changes?”An update replaces only the files listed in .claude/engine-manifest.json, and your own files are never on that list. Where you have edited an engine file, /update merges your edits with the new version. If you and the update changed the same lines, the file gets conflict markers for you to resolve. Critical engine files are always replaced. The update saves a backup to .claude/engine-backups/ before it changes anything.
How Do I Undo an Update?
Section titled “How Do I Undo an Update?”Type /update rollback, or ask Claude to undo the last update. Claude restores the engine files from the backup, reports what it restored and commits the result. If you work in a terminal, you can also run this command.
bash Infrastructure/Scripts/update-engine.sh --rollbackThe rollback restores AI Business OS engine files only. Claude tells you if the same update also changed PRIMA Project Management files.
What Do the /update Error Messages Mean?
Section titled “What Do the /update Error Messages Mean?”| Message | What to Do |
|---|---|
| No upstream remote | Nothing. The script adds it from the manifest |
| No git access | Check your git authentication, for example with gh auth status |
| jq not installed | Install it, for example with brew install jq on macOS |
| Manifest missing | The workspace needs a manual update. Contact support |
| PRIMA upstream fetch fails | The engine update still applies. The PRIMA Project Management update is skipped, usually because of an authentication problem |
My Session Ended or Ran Out of Context. How Do I Pick Up Again?
Section titled “My Session Ended or Ran Out of Context. How Do I Pick Up Again?”Your files and project records stay on disk when a session ends. Start a new session and run /day, then tell Claude what you were working on. With PRIMA Project Management, /day shows where you stopped on each project. With PRIMA Memory as well, Claude can search your earlier sessions. If a session stops in the middle of a task, copy Claude’s last summary into the new session and ask it to continue.
Where Did the Copywriting Skill Go?
Section titled “Where Did the Copywriting Skill Go?”AI Business OS 3.0 removed six skills from the template, which are copywriting, search engine optimisation, email drafting, creating presentations, processing spreadsheets and processing documents. A workspace installed before 3.0 keeps any of them it already has, because an update never deletes a file. All six are available as skill packs in the GenAI Skills Academy learning community.
Can I Change the Project Numbering Format?
Section titled “Can I Change the Project Numbering Format?”Your project register decides the format. A new AI Business OS workspace starts at P001, and a workspace that already uses another format keeps it. /newproject never introduces a second format and never reuses an ID. With PRIMA Project Management, /setup can set a different format before you create your first project.
See AI Business OS Troubleshooting for more.
PRIMA Project Management
Section titled “PRIMA Project Management”/day Says “State File Not Found”
Section titled “/day Says “State File Not Found””The file .claude/state/state.json is missing from the folder Claude is working in. First check that VS Code has your workspace folder open. In a new workspace the installer puts this file in place before you run /setup, so if it is missing the installation did not finish. See Getting Help. If you are moving from an older state format, run Scripts/migrate-to-prima.sh.
validate-state.sh Reports Errors
Section titled “validate-state.sh Reports Errors”Errors stop the script, and warnings let it carry on.
| Problem | Type | Fix |
|---|---|---|
| Invalid status value | Error | Use one of in-progress, paused, overdue or archived |
| Duplicate project ID | Error | Give one of the projects the next free ID |
| Invalid project ID format | Error | Use a letter prefix of up to ten letters, an optional hyphen and three to six digits, such as P001 |
| Invalid workspace type | Error | Set workspace.type to personal, client or internal |
| Paused without reason | Warning | Add a pausedReason |
| Session history holds earlier months | Warning | Run Scripts/archive-history.sh, which moves them into the monthly archive |
| Missing or invalid category | Warning | Set category to one of the values in state.schema.json |
| Duplicate project name | Warning | Rename one project or archive the duplicate |
| Workspace identity incomplete | Warning | Fill in workspace.name, id and type |
Sync Stops With “WORKSPACE MISMATCH”
Section titled “Sync Stops With “WORKSPACE MISMATCH””/sync and /night stop when the repository named in workspace.githubRepo in state.json does not match your git remote. Run git remote get-url origin to see the remote, then correct workspace.githubRepo. To skip the check, set the value to an empty string.
My Calendar Is Missing From the Daily Briefing
Section titled “My Calendar Is Missing From the Daily Briefing”For calendar events in /day, check that .claude/config/integrations.json exists and that calendar.enabled is true. The calendar MCP server also needs to be set up in Claude Code. A server that signs in through your browser needs you to sign in again on each machine.
/night Says “No Projects Detected”
Section titled “/night Says “No Projects Detected””/night matches the work done in the session to your projects by name and topic. If it misses a project, tell /night what you worked on, for example /night worked on P001 and P003.
My state.json Is Corrupted
Section titled “My state.json Is Corrupted”Copy the most recent good backup from .claude/state/backups/ over state.json, then run Scripts/validate-state.sh to check it.
Do I Need PRIMA Memory?
Section titled “Do I Need PRIMA Memory?”No. Without PRIMA Memory, /resume works from your session checkpoints and the session history in state.json, and /day works the same either way. PRIMA Memory adds full transcripts, detail levels and search by meaning.
Does /newclient Register a Project?
Section titled “Does /newclient Register a Project?”No. /newclient comes from AI Business OS and creates the client folder only. Ask Claude to register the client as a project, and the project-tracking skill adds it to state.json.
Why Do I Need Node for the Dashboard?
Section titled “Why Do I Need Node for the Dashboard?”/dashboard and the Today view in /day run a build script that needs Node 18 or later. Every other command works without Node.
The Shared Dashboard Has No Icons
Section titled “The Shared Dashboard Has No Icons”The page loads its icons and font from the assets/ and fonts/ folders beside it. Send both folders with the HTML file.
My State Backups Keep Growing
Section titled “My State Backups Keep Growing”backup-state.sh keeps 30 days of backups and deletes older ones each time it runs. Add .claude/state/backups/ to your .gitignore so the backups stay out of your repository.
See PRIMA Project Management Troubleshooting for more.
PRIMA Memory
Section titled “PRIMA Memory”Search Does Not Find My Older Sessions
Section titled “Search Does Not Find My Older Sessions”Semantic search covers only the sessions in its index. A result may warn that some session files are not yet indexed. Run rebuild_index with confirm set to true, or ask Claude to rebuild the PRIMA Memory index. The rebuild runs in the background, newest sessions first, and get_index_status shows its progress. Keyword search covers every session the whole time, and Rebuilding the Index explains the rebuild.
Results Say They Are Keyword-Only
Section titled “Results Say They Are Keyword-Only”The semantic part of that search failed or the index is still building, so the results come from keyword matching alone. Run get_index_status to see the index coverage.
Does PRIMA Memory Send My Conversations Anywhere?
Section titled “Does PRIMA Memory Send My Conversations Anywhere?”No, the index and its search run on your machine. The only network access is a one-time download of the embedding model, about 23 MB from Hugging Face, the first time PRIMA Memory needs it. Keyword-only searches never load the model, and Privacy and Your Data gives the details.
PRIMA Memory Finds Nothing at All
Section titled “PRIMA Memory Finds Nothing at All”PRIMA Memory takes its workspace from the folder Claude Code was started in. Open your workspace folder in VS Code before you start Claude Code. If the server was started elsewhere, it reads and indexes that folder.
Can I Open a VS Code or Codex Session From Search Results?
Section titled “Can I Open a VS Code or Codex Session From Search Results?”No. get_session_details opens Claude Code sessions from your workspace and shared project log entries only. VS Code Copilot Chat and Codex sessions appear in search results but cannot be opened.
I Updated PRIMA Memory and Nothing Changed
Section titled “I Updated PRIMA Memory and Nothing Changed”Restart Claude Code after an install or update so the new version loads.
See PRIMA Memory Troubleshooting for more.
PRIMA CRM
Section titled “PRIMA CRM”The CRM Server Will Not Start
Section titled “The CRM Server Will Not Start”PRIMA CRM needs the AI Business OS project register at .claude/state/state.json, with a list of projects inside it. If the file is missing, run /setup in AI Business OS. Start Claude Code from your workspace root, because the server looks for the register in the folder it starts in.
Why Does Sync Say “Not Built Yet”?
Section titled “Why Does Sync Say “Not Built Yet”?”PRIMA CRM can read which email, calendar and meetings services you have connected, but the code that fetches from them is not built in this release. Proton Mail, Google Calendar and Zoom report as Not built yet, and nothing syncs. See Email, Calendar and Meeting Sync.
crm_sync accept Says the ID Does Not Match
Section titled “crm_sync accept Says the ID Does Not Match”Use the eight-character ID from the review table, or the full ID. A prefix shorter than eight characters, or one that matches more than one waiting item, returns an error and changes nothing.
The CRM Dashboard Says “No CRM Database”
Section titled “The CRM Dashboard Says “No CRM Database””Run the dashboard script from your workspace root, because it looks for .prima-crm/crm.db in the folder you run it from. See The CRM Dashboard.
Why Is This Company Not Showing as Stale?
Section titled “Why Is This Company Not Showing as Stale?”Only active companies can be stale. Leads and past companies never are, and a company whose relationship has no cadence, such as internal or other by default, never goes stale. See Stale Clients and Contact Cadence.
How Do I Copy the CRM Database Safely?
Section titled “How Do I Copy the CRM Database Safely?”The database keeps recent writes in a second file, crm.db-wal. Copy all three database files together, or a copy of crm.db alone may miss your latest records.
I Merged Two Companies by Mistake
Section titled “I Merged Two Companies by Mistake”A confirmed merge cannot be undone. The first crm_company merge call is always a dry run, so read its report and both company profiles before you confirm.
See PRIMA CRM Troubleshooting for more.
PRIMA Scholar
Section titled “PRIMA Scholar”Why Is My Command Called /prima-scholar:scholar?
Section titled “Why Is My Command Called /prima-scholar:scholar?”When PRIMA Scholar is installed as a Claude Code plugin, Claude Code puts the plugin name before each command and skill. The commands work the same way.
CORE Results Are Missing
Section titled “CORE Results Are Missing”CORE needs a free API key, so set CORE_API_KEY and restart Claude Code. Without it, searches skip CORE and say so, as API Keys and Configuration explains.
My API Keys Disappeared After I Reinstalled
Section titled “My API Keys Disappeared After I Reinstalled”Versions before 2.2.1 deleted most API keys when install.sh ran again. Update to 2.2.1 or later, then add the keys back to the env block of the prima-scholar-search entry.
A Search Reports “Tool Not Found”
Section titled “A Search Reports “Tool Not Found””If the missing tool parameter is published_after, your search server is older than 2.1.0, so rebuild it and restart Claude Code.
The Literature Watch Keeps Showing the Same Papers
Section titled “The Literature Watch Keeps Showing the Same Papers”The watch skips papers it has already reported by passing their DOIs to the search. If the same papers return, the previous run did not update its state file. Check that the run finished and that its JSON file lists the DOIs. See Literature Watch.
The Literature Watch Found Nothing This Week
Section titled “The Literature Watch Found Nothing This Week”Databases add new papers days or weeks after publication. Widen the scan with since and an earlier date, or accept a quiet week.
A PDF Imported With No Text
Section titled “A PDF Imported With No Text”PRIMA Scholar cannot read text from scanned, image-only PDFs, because it has no character recognition. It cannot import password-protected files either, and files over 100 MB may time out.
My Changes to a PRIMA Scholar Skill Were Overwritten
Section titled “My Changes to a PRIMA Scholar Skill Were Overwritten”The installer replaces the commands, skills and agents it ships on every run. Copy one to a new name, such as my-researching-topics, and edit the copy. The installer never touches renamed copies.
Git Warns About an Embedded Repository
Section titled “Git Warns About an Embedded Repository”You cloned PRIMA Scholar inside your workspace. Ask Claude to follow fix-nested-repo.md from the PRIMA Scholar repository, which moves the clone to ~/Developer/prima-scholar, removes it from git tracking and reinstalls.
See PRIMA Scholar Troubleshooting for more.