catalyst-basics

⚠️ PRE-FLIGHT CHECK: Before creating any project files, confirm that .catalystrc and catalyst.json exist in the project directory. If they don't:

1. Use MCP (CatalystbyZoho_List_All_Organizations → CatalystbyZoho_List_All_Projects) to get the org ID and project ID.
2. Run: catalyst init --org <orgId> -p <projectId> -ni
3. Never ask the user to run catalyst init interactively. Never create these files manually — they are CLI-generated and must come from the CLI.

How It Works

1. MCP check first — Before reading any local files, look for CatalystbyZoho_* tools. If available, use MCP to get org ID, project ID, and all resource IDs instead of asking the user.
2. Account alignment check — do this before catalyst init — MCP and CLI can be authenticated as different accounts. Before running catalyst init --org <id>, verify they match:

   catalyst whoami
   

   Compare the org name shown to the result of CatalystbyZoho_List_All_Organizations. If they differ, run catalyst login --force to re-authenticate the CLI before proceeding.
3. New to Catalyst? — If the user is setting up Catalyst for the first time or asking "how do I start", load references/quick-start.md for the full walkthrough.
4. Console navigation — If the user asks how to find IDs, create tables, set permissions, or configure CORS in the console, load references/console-ui-guide.md.
5. Pre-flight — Confirm .catalystrc and catalyst.json exist. If missing, use MCP to get org/project IDs and run catalyst init --org <orgId> -p <projectId> -ni. Never use interactive catalyst init.
6. Project structure — Load references/project-basics.md for directory layout, catalyst.json, IDs, and dev-to-prod checklist.
7. CLI questions — Load references/cli.md for the exact command, flags, and safety rules.
8. Answer — Provide the specific ID path or CLI command needed. Never ask the user to manually look up IDs when MCP is connected.

Triggers

Use this skill for: "how do I start a Catalyst project", "what is .catalystrc", "where do I find my Table ID / ZAID / Segment ID / Project ID", "difference between Development and Production", "Catalyst project structure", "catalyst.json explained", catalyst init, catalyst deploy, catalyst serve, catalyst login, "how do I set up Catalyst with Claude", "how do I use Catalyst in Cursor", "how do I use Catalyst with GitHub Copilot", "which service should I use", "what Catalyst service for X", or any question about Catalyst IDs, environments, organizations, IDE setup, architecture decisions, or CLI subcommands.

MCP Connection Check (Do This Before Anything Else)

Before reading .catalystrc, asking the user for IDs, or doing anything project-related — check whether Zoho MCP tools are available in your tool list.

Look for tools prefixed with CatalystbyZoho_ (e.g., CatalystbyZoho_List_All_Projects, CatalystbyZoho_List_All_Tables).

If MCP tools ARE available:

• Use CatalystbyZoho_List_All_Organizations to get the org ID
• Use CatalystbyZoho_List_All_Projects to get the project ID
• Use MCP tools to fetch table names, bucket names, ZAIDs, and all other project details directly — do NOT ask the user to copy-paste IDs from the console

If MCP tools are NOT available:

• Prompt the user to connect Zoho MCP before proceeding
• Guide them to: VS Code → Settings → MCP (or Claude Desktop claude_desktop_config.json) and add the Catalyst MCP server
• Fall back to reading .catalystrc and catalyst.json from the local project directory only as a last resort

Never ask the user to manually look up IDs from the console if MCP is connected. Every project detail — org ID, project ID, table IDs, ZAIDs, bucket names — is retrievable via MCP tools. Asking the user to hunt for IDs when MCP is available wastes time and introduces copy-paste errors.

References

Load the relevant reference file for detailed information: