ARK

Which Files to Share

When you use a chat-style AI tool, you have to paste the right files in for the model to do useful work. Too few files and it's guessing; too many and you burn context on irrelevant code. This page tells you exactly which files to share for common customization tasks.

If you're using an agent-style tool (Claude Code, Cursor, Windsurf), you mostly don't need this page — the tool reads the repo itself. Skip to Example Modifications.

The universal rule

Always start with CLAUDE.md. It's the repo's configuration file for AI tools. Without it, every suggestion starts from generic-web-app assumptions instead of ARK-specific ones.

After CLAUDE.md, share the files that the task actually touches. Use the per-product maps below to figure out what those are.

Reading the file maps

Each product's README.md has a "File Map" table that covers the full repo. The tables here are a simplified view oriented around tasks — "I want to do X, which files matter?"

For the complete per-file reference, open README.md in your product repo and use that.

Track (CRM) — task-to-file map

  • src/theme.css — design tokens
  • public/logo.svg — the logo
  • src/components/Brand.tsx — the wordmark component
  • tailwind.config.ts — if you're adding new Tailwind colors

Add a field to contacts or companies

  • supabase/schema.sql — to see the current column list (don't edit, but share for context)
  • supabase/migrations/ — you'll add a new migration here
  • src/features/contacts/ContactForm.tsx
  • src/features/contacts/ContactDetail.tsx
  • src/features/contacts/types.ts

For companies: replace contacts/ with companies/ throughout.

Change board or stage behavior

  • src/features/boards/ — entire directory
  • src/features/boards/stage-colors.ts — stage color definitions
  • src/features/deals/DealCard.tsx — how deals render on the board
  • supabase/schema.sql — the boards, stages, deals tables

Add a new automation action

  • src/features/automations/actions.ts — action registry
  • src/features/automations/action-forms/ — UI forms per action
  • supabase/functions/track-automation-runner/ — the runner Edge Function
  • CLAUDE.md — automation conventions are called out here

Add an integration (Slack, webhook, etc.)

  • src/features/integrations/ — existing integration patterns
  • supabase/functions/ — outbound calls usually go through an Edge Function for secret safety
  • src/lib/notify.ts — if you're adding a notification channel, follow this pattern

Rename or relabel UI text

  • src/i18n/strings.ts — centralized display labels
  • No migration needed — labels are UI-only

Comms — task-to-file map

Change branding or theme

  • src/theme.css
  • public/logo.svg
  • src/components/Brand.tsx

Add a message type

  • src/features/messages/types.ts
  • src/features/messages/MessageRenderer.tsx — dispatches on type
  • supabase/schema.sql — messages table schema
  • supabase/migrations/ — new column if you're adding one

Modify channel permissions

  • src/features/channels/permissions.ts
  • supabase/schema.sql — channel_members RLS policies
  • CLAUDE.md — permission conventions

Add a notification trigger

  • src/features/notifications/triggers.ts
  • supabase/functions/comms-notify/ — the notification sender
  • src/lib/notify.ts

Customize the Docs View (Ink integration)

  • src/features/docs-view/ — entire directory
  • Requires Ink's schema to be present (see multi-product setup)

Customize the Tasks View (Track integration)

  • src/features/tasks-view/ — entire directory
  • Requires Track's schema to be present

Pulse (Standups) — task-to-file map

Change branding or theme

  • src/theme.css
  • public/logo.svg

Change standup question logic

  • src/features/standups/questions.ts
  • src/features/standups/StandupForm.tsx
  • supabase/schema.sql — standup_questions table

Modify the Slack integration

  • src/features/integrations/slack/ — entire directory
  • supabase/functions/pulse-slack-webhook/
  • Environment: SLACK_* keys in Vercel

Add a new poll type

  • src/features/polls/types.ts
  • src/features/polls/PollRenderer.tsx
  • src/features/polls/PollForm.tsx
  • supabase/schema.sql — polls, poll_options tables

Customize reminder timing

  • src/features/reminders/
  • supabase/functions/pulse-reminder-sender/ — the cron job that sends reminders

Ink (Documents) — task-to-file map

Change branding or theme

  • src/theme.css
  • public/logo.svg

Add a block type to the editor

  • src/features/editor/blocks/ — existing block implementations
  • src/features/editor/BlockRegistry.ts
  • src/features/editor/Editor.tsx — the Tiptap/Slate-based editor
  • supabase/schema.sql — blocks table (content is JSONB)

Change sharing or permissions

  • src/features/sharing/
  • supabase/schema.sql — space_members, document_shares RLS
  • CLAUDE.md — sharing rules are called out

Customize the tag / organization UI

  • src/features/tags/
  • src/features/documents/DocumentSidebar.tsx

Add a document template

  • src/features/templates/
  • src/features/templates/registry.ts

Cross-product: shared files

Every ARK product includes these. When a task affects them, share the ARK product's version, not any other product's.

FileWhat it does
CLAUDE.mdAI conventions and guardrails
README.mdHuman-facing file map and quickstart
src/lib/supabase.js (or .ts)Supabase client — rarely needs edits
src/lib/license.jsLicense validation — don't edit
src/theme.cssDesign tokens
src/App.tsx (or equivalent)App root, routing, providers
supabase/schema.sqlFull schema — share for context, edit via migrations
package.jsonDependencies and scripts
.env.exampleThe env var template

When in doubt, share less

It's tempting to paste the whole repo in. Don't. Large, irrelevant file dumps dilute the model's attention and produce worse answers.

A good rule of thumb:

  • 1–3 files: for targeted changes (a single bug fix, a styling tweak, adding one column)
  • 4–7 files: for small features (new field end-to-end)
  • 8+ files: you're probably describing the task too broadly — split it into sub-tasks

If the model says "I need to see X to answer correctly," paste X. If it doesn't ask, assume what you gave was enough.

Using the README file maps directly

Every product's README.md in the repo has a more detailed file map than this page. If a task falls outside the common categories above:

  1. Open README.md in the product repo.
  2. Find the "File Map" or "Project Structure" section.
  3. Identify the directory most related to your task.
  4. Share every file in that directory (or enough to cover the change).
  5. Also share CLAUDE.md and any file the first set of files imports from heavily.

Where to go next