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.

1. 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.
2. 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.
3. 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.
4. Project structure — Load references/project-basics.md for directory layout, catalyst.json, IDs, and dev-to-prod checklist.
5. CLI questions — Load references/cli.md for the exact command, flags, and safety rules.
6. 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: