Foundation & Setup
Part 4 of 7 · Reviewed 31 Aug 2026

Foundation & Setup

Choose a supported Claude Code surface, configure the smallest permissions, and keep every production side effect behind an independent controlled executor.

Self-paced Beginner Level
Section 01

What Is a Terminal?

The terminal is one supported way to run Claude Code. Claude Code also has desktop and IDE surfaces; choose the current option that fits your environment and organizational controls.

It's Just a Text Window

A terminal is a text-based window where you type commands to your computer. Commands may read, create, change, execute, install, transmit, or delete data depending on their permissions, so the working directory and exact command matter.

Think of it this way: the terminal is like texting your computer. You send a message (a command), and your computer responds with a result. You're already used to this concept from WhatsApp or Messenger — you type something, you get something back. Same idea.

The comparison ends there: shell commands can have immediate side effects, can expand variables and wildcards, and can run downloaded code. Read and understand each command, resolve its targets, and ask a qualified operator when uncertain.

Why Not Just Use the Regular Interface?

A terminal is useful for versioned commands, local development, and inspecting exactly what ran. It is not mandatory for every Claude Code workflow: Anthropic also documents desktop and IDE options. A surface never grants safe access by itself; its selected folder, tools, network, credentials, and permission mode define the real boundary.

Natural-language instructions do not remove the need to review commands, diffs, dependencies, permissions, and outputs. Begin in a disposable learning folder with no client data, credentials, production account, or unrelated files.

What It's Called on Your Computer

  • Mac: It's called "Terminal" — a built-in app that comes with every Mac.
  • Windows: It's called "Command Prompt" (cmd) or "PowerShell" — also built-in. There's also "Windows Terminal" which you can download from the Microsoft Store for a nicer experience.
  • Linux: Usually just called "Terminal" — if you're on Linux, you probably already know this.

How to Open It

Mac
Open Terminal on Mac
Press Cmd + Space to open Spotlight Search. Type "Terminal" and press Enter. A window will appear with a blinking cursor. That's your terminal. Done.
Windows
Open Terminal on Windows
Press the Windows key on your keyboard. Type "cmd" or "PowerShell" and press Enter. A window will open with a blinking cursor. That's your terminal. Done.

What You'll See

When you open the terminal, you'll see a window — dark or light background — with a blinking cursor waiting for you to type. That's it. No buttons, no menus, no icons. Just a cursor.

It might show something like this before the cursor:

mazin@MacBook-Pro ~ %

Or on Windows:

C:\Users\Mazin>

This is just your computer telling you who you are and where you are (which folder you're in). You can completely ignore it. The important thing is the blinking cursor — that's where you type.

What If Something Goes Wrong?

Terminal commands can change or delete files, install software, and expose secrets. Read every command, confirm its working directory and targets, avoid commands you do not understand, and never paste access tokens into shell history. A typo may be harmless, but do not assume every command is.

If you ever feel "stuck" in the terminal — like it's not responding or something weird is happening — just press Ctrl + C. That's the universal "cancel" button in the terminal. It stops whatever is running and gives you your cursor back.

Common Commands (Don't Memorize — Just Know They Exist)

You don't need to memorize any of these. You'll copy-paste the few commands you need during setup. But here are the most basic ones so they don't surprise you:

  • ls (Mac/Linux) or dir (Windows) — lists the files in your current folder. Like opening a folder and looking at what's inside.
  • cd folder-name — goes into a folder. Like double-clicking a folder to open it.
  • cd .. — goes back one folder. Like clicking the "back" button.
  • mkdir name — creates a new folder. Like right-clicking and choosing "New Folder".

These commands are enough for the exercise. Real setup and maintenance may require more expertise; do not delegate unfamiliar commands or destructive targets to a model without review.

Your First Terminal
Animated
$
Documents/  Downloads/  Desktop/  my-project/
$
~/my-project $
~/my-project $
skills/  .env  CLAUDE.md  package.json
// That's it. You just used a terminal.
Pro Tip

Use Anthropic's current Claude Code quickstart for supported installation and login paths. Prefer the smallest project directory and permission set; keep production credentials and media-buying write access outside the model session.

Section 02

Claude Surfaces and Permission Boundaries

Capabilities vary by plan, organization, surface, connector, environment, and permission mode. Check current official documentation instead of relying on a permanent “chat versus code” feature table.

Claude Chat

Chat is conversation-first. Depending on the current product, plan, and administrator configuration, it may support files, web search, code execution, skills, or connectors. Do not infer access from the product name; inspect the enabled tools, connected accounts, retention terms, and data boundary for the actual session.

  • Use only organization-approved accounts, projects, connectors, and data classes
  • Check whether uploaded files or connected sources contain client, customer, employee, credential, or third-party data
  • Assume retrieved content can contain prompt injection; a connector does not authorize a side effect
  • Keep media-buying outputs as drafts unless a separate reviewed system enforces execution controls

Claude Code

Claude Code can run in CLI, desktop, IDE, web, or managed environments documented by Anthropic. Its effective authority comes from the selected folder, environment, tools, network, identities, policy, and permission mode—not from the model name.

  • Limit the working directory to an isolated project with no unrelated or production secrets
  • Allow only the tools and network destinations required for the approved task
  • Keep analysis on a read-only service identity and minimum authorized fields
  • Keep write credentials in an independent server-side executor; the model never receives them
  • Review diffs, commands, dependencies, tool calls, and permission requests; prompt confirmation alone is not an execution control

Why This Matters for Media Buying

Here's where it gets real. Let's compare what happens when you ask for the same thing:

  • Either surface can draft instructions or analysis from the context it is permitted to receive
  • A controlled Code environment can call a tenant-scoped read service and prepare a sourced report from minimum authorized fields
  • The model may draft a typed budget proposal, but it has no write credential and no approval authority
  • A deterministic executor separately enforces server-side reviewer and account binding, schemas, policy, full immutable diff, exact approval, caps, stable idempotency, audit, rate limits, stop, and rollback

The important distinction is therefore assigned authority, not “talk versus action.” Keep the model read-only and proposal-only regardless of surface.

A Day-in-the-Life Comparison

In a fictional learning scenario, Chat receives a small synthetic table and drafts questions. A controlled Code workflow queries the same allowlisted synthetic fields through a read identity, validates account, schema, currency, time zone, attribution, freshness, pagination, and rate limits, then produces facts, ranked hypotheses, gaps, and an inert proposal. Neither surface changes a live account.

Measure review time and quality on your workload; do not promise a fixed speed-up. Structured access can reduce transcription, but it also introduces identity, authorization, tenant, schema, availability, and operational risks.

Chat vs Code — Side by Side
Animated
claude.ai — Chat
You: Review this synthetic campaign table
Claude:
// Instructions only. You do the work.
Output: Text instructions
Claude Code — Terminal
$
Reading allowlisted synthetic fields...
Typed proposal validated; no write credential present
Immutable diff: entity_demo · before 400 · after 450
Status: PROPOSAL_ONLY · exact approval required
// No campaign or budget was changed.
Output: Reviewable proposal
Real Talk

Think of each surface as an environment with a specific tool and data policy. For this course, the model drafts; a named person reviews; and only an independent, deterministic, server-side executor may perform an exact approved change under caps, idempotency, audit, stop, and rollback.

Section 03

Choose a Current Access and Billing Path

Plans, included products, prices, limits, and authentication options change. Use current official documentation and measure the cost of the complete workflow.

Supported Paths

Anthropic currently documents several ways to authenticate Claude Code. Availability depends on account, region, organization, and administrator policy:

  • Claude subscription: Pro, Max, Team, or Enterprise may include Claude Code under the plan's current shared usage limits.
  • Claude Console: API-funded access uses Console workspaces, usage reporting, and spend controls.
  • Enterprise providers: supported cloud or organization-managed authentication may add identity, network, billing, and policy controls.

How to Choose

Start with a low-risk synthetic pilot and the access path your organization approves. Observe actual usage, task completion, review effort, latency, support, data terms, administration, and total cost before changing plans or expanding users. Rate limits are workload- and plan-dependent; design bounded queues, backoff, budgets, and stops instead of assuming uninterrupted capacity.

Compare the Complete System

Do not compare a subscription price with a person. Include implementation, integration, evaluations, review, security, privacy, support, monitoring, incidents, platform/API costs, failures, change management, and exit. Capability and reliability must be measured; a model is not an employee and does not operate safely without ownership and controls.

Feature Subscription Console / API Organization-managed
Billing Current plan terms Measured usage Contract and provider terms
Identity Claude account Console workspace Central policy / SSO where supported
Limits Shared plan limits Spend and service limits Contract and admin controls
Cost evidence Usage view Console reporting Organization analytics
Decision basis Approved use case, controls, measured workload, support, and current terms
Current Official Sources

Check Claude pricing, Claude Code quickstart, authentication options, and cost management at decision time. This lesson does not cache plan entitlements or price claims.

Section 04

What Is an API? (Restaurant Edition)

APIs are versioned contracts used by authorized services. They do not grant the model identity, permission, approval, correctness, or safe execution.

The Restaurant Analogy

Imagine you're sitting at a restaurant. Here's how it works:

  • YOU = an authenticated, tenant-scoped client service—not the model itself
  • THE MENU = API documentation (lists everything you can order, with descriptions and rules — "no substitutions on the grilled chicken")
  • THE WAITER = the API itself (takes your order to the kitchen, brings back the result)
  • THE KITCHEN = the platform's system (Meta, Shopify, etc. — does the real work behind the scenes)

You never walk into the kitchen. You never touch the stove. You read the menu, tell the waiter what you want, and you get your food. That's exactly how APIs work.

Translating the Analogy to Tech

Here's the same analogy in technical terms — don't worry, they map perfectly:

  • "Ordering food" = making an API request (sending specific data to the platform)
  • "Getting your plate" = receiving an API response (the platform sends data back)
  • "The menu items" = API endpoints (specific things you can ask for — "create campaign", "get ad performance", "update product price")

Separate Read From Change

HTTP APIs support several methods and platform-specific semantics. For governance, distinguish requests that only read approved data from requests that create, update, delete, publish, send, or otherwise cause a side effect:

  • READ (GET) — Looking at the menu. You're asking for information without changing anything. "Show me my campaign performance." "What products are in stock?" "How many orders came in today?"
  • CHANGE — A side effect may use POST, PATCH, PUT, DELETE, GraphQL mutations, or another platform operation. It belongs behind a separate deterministic executor with a narrow write identity and exact approval.

In both paths, validate the API version, authentication, authorization, tenant and account binding, schema, units, pagination, response size, rate limits, retries, errors, and audit evidence. The model never receives the access token.

API Request / Response Flow
Animated
Read Service
Tenant-scoped identity
→
Request: Read allowlisted metrics
Account: synthetic_demo
Meta Ads
The Kitchen
←
Response: schema-valid rows
source and capture time recorded
// Simplified read example; verify the platform's actual versioned contract.
Key Takeaway

You may not need to implement the connector personally, but a qualified owner must review the exact API contract, permissions, data definitions, rate-limit behavior, failure handling, tests, and operational controls. Natural-language instructions are not a substitute for that implementation.

Section 05

What Is API Documentation?

If the API is a waiter, then documentation is the restaurant's menu — the rulebook that tells you what you can order and how.

Documentation = The Rulebook

Every platform that offers an API also provides documentation (often called "docs"). Documentation is a detailed guide that explains:

  • What you CAN request — which endpoints (menu items) are available
  • What format to use — how to structure your request (like specifying "medium rare" for your steak)
  • What responses to expect — what the platform will send back
  • What errors might happen — "we're out of the salmon" (the API equivalent of an error message)
  • What permissions you need — some menu items are only for VIP members (restricted API endpoints)

Where to Find Docs

Every major platform has a developers section with their documentation:

  • Meta (Facebook/Instagram Ads): developers.facebook.com
  • Shopify: shopify.dev
  • Google Ads: developers.google.com/google-ads
  • TikTok Ads: business-api.tiktok.com

Do You Need to Read Docs Yourself?

Yes, someone accountable must verify them. Skills can summarize documentation, but they are not a source of truth and may be stale or wrong. Pin an API version in reviewed code, link the current official reference, and assign an engineer or operator to review changelogs before release.

As of this lesson's August 2026 review, examples use Meta Graph API v26.0. Verify the current supported version in Meta's official changelog before implementation. A failed write must stop; documentation review never authorizes an automatic schema mutation or retry.

What a Docs Entry Looks Like (Simplified)

Just so you recognize it if you ever see one, here's a simplified version of what an API documentation entry looks like:

Endpoint: POST /v26.0/act_{ad_account_id}/campaigns

Description: Creates a new ad campaign.

Parameters:
  name          (required)  — Campaign name
  objective     (required)  — OUTCOME_SALES, OUTCOME_TRAFFIC, etc.
  status        (required)  — PAUSED (hard-coded by the controlled executor)
  special_ad_categories (required) — [] or ["HOUSING", "CREDIT"]

Response:
  { "id": "123456789" }

Errors:
  100 — Invalid parameter
  190 — Access token expired

This is a simplified teaching example, not a complete request contract. Review the pinned official reference, permissions, account state, validation rules, and error handling before use. Production writes belong behind a service that enforces tenant scope, PAUSED state, spend caps, idempotency, exact approval, and audit logs.

Why This Matters

Documentation helps maintain a versioned integration. On an API failure, stop writes, inspect the pinned official reference and changelog, make a reviewed code/config change, run contract tests and eval fixtures in a test account, then canary with rollback. Do not let a model invent a schema and retry a production write.

Section 06

What Is a Meta Access Token?

An authorized server-side service uses an access token to authenticate to Meta. The model must never receive the token or use it as its own identity.

The VIP Wristband Analogy

Imagine you're going to an exclusive club. At the door, they give you a wristband. That wristband proves you have permission to be there — without it, security won't let you in.

A Meta access token is a sensitive credential presented by a server-side integration. Its app, principal, scopes, assigned assets, validity, and Meta's policy determine what requests may be accepted. Authentication does not prove the request is appropriate or approved.

Token Lifetimes and Validation

Token type, lifetime, permissions, and revocation behavior depend on the app, user or system-user context, configuration, and current Meta policy. Do not hardcode lifetime assumptions:

  • Inspect token metadata: validate the app, principal, scopes, assets, issue time, and expiry before use.
  • Use least privilege: separate read-only analysis from tightly controlled write credentials and account allowlists.
  • Assume revocation is always possible: rotate credentials, monitor failures, and maintain a tested revoke-and-recover procedure. No token should be described or treated as permanently valid.

How to Get Your Token

Meta's interface and eligibility requirements change. Treat the following as a review pattern, then follow the current official Marketing API documentation for the selected app, business, principal, and environment.

Step 1
Go to Meta for Developers
Open Meta for Developers through an organization-approved administrator account. Confirm business ownership, intended use, app roles, and the correct development or production environment.
Step 2
Create a Business App
Use Meta's current app-creation flow and bind the app to the approved business. Record the owner, purpose, environments, assets, users, review status, and incident contacts.
Step 3
Add the Marketing API
Enable only the product and use case required by the reviewed design. Pin and monitor the supported Graph API version and changelog.
Step 4
Use a Test Environment
Use Meta's approved developer tools and test assets for learning. Explorer or user tokens are not a production identity, and no production account should be attached to the first exercise.
Step 5
Bind the Exact Assets
Allowlist the tenant, business, ad account, and permitted entities server-side. Test that the service rejects a wrong account or cross-tenant identifier.
Step 6
Separate Read and Write Permissions
The analysis service starts with the minimum read permission such as ads_read where applicable. Do not add ads_management to the model-facing service. If an approved use case truly requires a write, give a separate deterministic executor its own narrowly scoped identity and account/entity allowlists.
Step 7
Generate a Development Token
Use Meta's current official flow for the app and principal. Inspect the token in Meta's debugger and record its app, scopes, assets, issue time, and actual expiry. Do not assume a fixed lifetime or use an explorer token for production.
Step 8
Configure Production Identity & Rotation
Follow Meta's current official guidance for the appropriate user or system-user identity, app review, business assets, and least-privilege scopes. Store the credential in a managed secret service, monitor validity, rotate it, and test revocation/recovery. No token is assumed permanent.

Security: Keep Your Token Secret

A token may expose whatever access its principal, scopes, assets, and app state permit. Treat every token as a secret and minimize the damage possible if it is compromised:

  • Never share your token in chat messages, emails, or screenshots
  • Never commit it to a public code repository (like GitHub)
  • For local development, a permission-restricted, ignored .env may be acceptable; use a managed secret store in production and never expose secrets to the model or browser
  • If you think your token was exposed, immediately revoke it and generate a new one
Security Warning

Keep credentials in a managed server-side secret store and out of prompts, model context, screenshots, CSVs, browser storage, source control, URLs, and ordinary logs. Use separate read and write identities, rotate and revoke them, alert on misuse, and test recovery.

Section 07

Shopify Admin API Authentication

If Shopify data is required, authenticate a server-side app using Shopify's current supported flow and the minimum read scopes. The model should never receive the client secret or access token.

Same Concept, Different Platform

Shopify's current app setup is managed through the Dev Dashboard or Shopify CLI. New admin-created legacy custom apps can no longer be created; do not follow the retired “Develop apps” flow. See Shopify's official Dev Dashboard guide.

Think of it like giving a new employee specific access rights at your company. You don't give them the master key to everything — you decide exactly what they can see and do. "You can view inventory but you can't change pricing. You can read orders but you can't issue refunds." That's what Shopify's access scopes do.

Access Scopes = Permission Levels

Request only the scopes needed for the approved use case. Start read-only:

  • read_products — See your product catalog (names, prices, images)
  • read_inventory — Read inventory only when the workflow requires it
  • read_orders — Request only when necessary, with Shopify's protected-customer-data requirements and your privacy review satisfied
  • No default write scope: catalog changes should be staged and human-approved through a separate, narrow executor

Current Setup Pattern

Step 1
Create the App in Dev Dashboard
Create and configure the app in Shopify's Dev Dashboard or Shopify CLI. Choose the owning organization and document whether it serves your own store or external merchants.
Step 2
Choose the Supported Auth Flow
For a store owned by your organization, use Shopify's client-credentials flow where eligible; its access token is short-lived. For external merchants, use Shopify's approved authorization-code/token-exchange flow with merchant consent. Never paste credentials into a prompt.
Step 3
Configure Minimum Scopes
Select only required read scopes. Keep write access out of the analysis service; if a reviewed use case truly needs it, isolate it in a separate executor with exact approvals, idempotency, and rollback.
Step 4
Pin and Test the API Version
Pin the stable Admin GraphQL version 2026-07 for this August 2026 lesson, monitor Shopify's version header, and review the official versioning policy. Run contract tests against a development store before release.
Step 5
Authenticate Server-Side
Keep client credentials in a managed secret store and obtain tokens server-side through the selected flow. Validate shop and tenant binding on every request; rotate/revoke secrets and audit access.
Important

Legacy admin-created apps may behave differently, but that is not the current setup path for new apps. Keep legacy credentials isolated and plan migration; do not broaden scopes or copy permanent tokens into prompts or shared files.

Section 08

What Is Playwright? (A Browser Testing Tool)

Playwright can help inspect documentation and test owned web experiences. It does not make an integration future-proof, authorize collection, or safely repair API writes on its own.

Browser Automation, Explained

Playwright is a browser automation tool. In simple terms, it lets Claude Code open a web browser, navigate to websites, read pages, click buttons, and extract information — all without you touching anything.

Imagine having an invisible browser running in the background. Claude tells it: "Go to this URL. Read what's on the page. Bring the information back to me." That's Playwright.

Controlled Compatibility Workflow

A browser can assist a maintainer in reading official documentation, but retrieved text is untrusted input and a model may misinterpret it. Documentation is evidence for a reviewed change—not executable policy.

When an API contract may have changed:

  1. Stop the write path and preserve the error, request ID, redacted payload, and pinned version
  2. Review the current pinned official reference and changelog; never use search snippets or third-party schemas as authority
  3. Make a version-controlled code or configuration change with human review
  4. Run offline eval fixtures and contract tests in a test account, including permission, duplicate, partial-failure, and rollback cases
  5. Canary the approved build with tenant-scoped credentials, PAUSED state, spend caps, idempotency, monitoring, and rollback
  6. Promote only after explicit release approval; do not let the model mutate a schema or retry a production write

This controlled workflow may require an engineer and downtime for the affected write path. That is safer than guessing against a live account.

Other Uses for Playwright

Beyond documentation review, approved browser testing can support these bounded tasks:

  • Testing owned destinations: Verify URLs, consent flows, layout, and accessibility in a test environment
  • Reviewing official docs: Capture a source and date for a maintainer; do not auto-apply the result
  • Inspecting your own store: Validate approved, substantiated product claims and catalog state
  • Permitted public research: Use official tools, manual review, or licensed feeds within terms, robots directives, rate limits, and law; do not silently scrape competitors
Controlled Compatibility Workflow
Animated
Making API call to Meta...
Error: Parameter 'special_ad_category' format changed
Write path blocked; opening maintenance incident...
Opening Meta docs via Playwright...
Reading updated parameter format...
Maintainer drafts a version-controlled change...
Running contract tests and eval fixtures in a test account...
Tests passed; canary awaits release approval.
// No automatic production retry or schema mutation.
What Makes an Integration Durable

Durability comes from pinned official contracts, reviewed changes, contract tests, eval fixtures, test accounts, canaries, observability, and rollback. A browser and a prompt can assist maintenance; neither may silently change production behavior.

Section 09

Reviewed Setup: From Synthetic Sandbox to Ready

Interfaces and install commands change. Use Anthropic's current quickstart, verify each command and target, and begin in an isolated folder with synthetic data and no media-buying credentials.

Step 1
Choose an Approved Access Path

Use the current Claude Code quickstart and authentication guide. Select an organization-approved subscription, Console, or supported provider; check current pricing and limits.

Step 2
Choose the Supported Interface

The official quickstart lists CLI, desktop, web, and IDE interfaces. This exercise uses the CLI only if your organization permits it. Desktop can provide a graphical Code surface; neither interface should be opened on a directory containing client data or production secrets.

Step 3
Install From the Current Official Guide

As of this review, Anthropic recommends native installation and also documents Homebrew, WinGet, Linux package managers, and desktop options. Do not rely on this lesson for a permanent install command; inspect the official domain, method, prerequisites, update behavior, and security policy before running it.

After installing by the reviewed method, verify the binary:

claude --version
Step 4
Authenticate and Inspect the Session

Launch claude and follow the official login flow. Check the account, organization, model, working directory, enabled tools, network, connectors, and starting permission mode. Authentication to Claude is separate from every Meta or Shopify credential.

Step 5
Create Your Project Folder

Create a dedicated folder for your media buying work. Type these two commands:

mkdir my-media-buying
cd my-media-buying

The first command creates a learning folder and the second enters it. Confirm the resolved path. Use only synthetic fixtures here; do not copy client exports, screenshots, tokens, or production configuration into the model workspace.

Step 6
Configure Secrets Safely

Do not place Meta or Shopify secrets in the Claude Code project, an .env the model can read, prompts, browser tools, source control, URLs, or ordinary logs. Use synthetic identifiers in the lesson:

TENANT_ID=tenant_demo
META_AD_ACCOUNT_ID=account_demo
DATA_MODE=synthetic
WRITE_MODE=disabled

Production credentials belong to separate server-side services in a managed secret store. Use one minimum-scope read identity for collection and a different, narrowly scoped write identity only inside the deterministic executor. Test rotation, revocation, tenant binding, audit, and recovery.

Step 7
Add No Connector by Default

The exercise does not require MCP or browser access. If an approved test needs a connector, select it from current official Claude Code MCP guidance and the connector publisher's official source. Review publisher, package and version, permissions, network destinations, data handling, prompt-injection risk, update policy, and removal. Pin the approved version; never grant it media-buying credentials.

Step 8
Launch Claude Code

Confirm you are inside the isolated learning folder, then launch the reviewed installation:

claude

Inspect the working directory, enabled tools, account, network, and permission mode. Ask it to read a harmless synthetic fixture; do not attach a platform or add a credential.

For a later learning session:

  1. Open Terminal
  2. Navigate to your project folder: cd my-media-buying
  3. Type: claude

These steps start a model session, not a production media-buying system. Production requires the separate read service, proposal schema, exact approval service, deterministic executor, evaluations, monitoring, incident path, and rollback described in this framework.

Learning Environment Ready

You have an isolated synthetic workspace, not production authorization. Re-check official setup and pricing, update behavior, permissions, and organizational policy over time. Part 5 adds reviewed instructions and evaluations; it does not expand the model's authority.

Your Synthetic Workspace Is Ready for Review

Part 5 covers versioned Skills and SOPs as instructions that still require permissions, task-specific evaluations, human review, and deterministic controls.

Continue to Part 5: Skills & SOPs