Before You Start · GoingNinja Manual Knowledge Wiki

It is written for the case where a reader has no prior knowledge of the repo family and needs to understand what must already exist before bootstrap, deployment, or audit can work.

If you are new to the machine surfaces themselves, read these first:

flowchart TD
  A["Provider owners
  and accounts"] --> B["Local CLI sessions
  and automation tokens"]
  B --> C["Bootstrap
  and repo creation"]
  C --> D["Branches
  and pipelines"]
  D --> E["Preview
  deployment"]
  E --> F["Live
  domain"]

Show diagram source

flowchart TD
  A["Provider owners
  and accounts"] --> B["Local CLI sessions
  and automation tokens"]
  B --> C["Bootstrap
  and repo creation"]
  C --> D["Branches
  and pipelines"]
  D --> E["Preview
  deployment"]
  E --> F["Live
  domain"]

Flow: what must be in place before machines can safely create, verify, and launch a product repo.

1. What Must Exist Before Bootstrap

GoingNinja can generate a product repo, but it cannot invent provider accounts or domain ownership.

Before the first real product starts, you need:

a GitHub account or organization that can own the product repository
a GitHub CLI session or token so the repo can be created and pushed
a deployment account such as Vercel if the product runtime is going to be hosted there
a deploy token or CLI login for that deployment provider if the work is automated
a domain or subdomain plan for where the product should live
a pre-launch preview host plan, which by default is www.preview.<product-domain>
a DNS provider for that domain
optionally a Cloudflare account if DNS, Pages, or Access should run there
any additional provider accounts required by the confirmed product requirements, such as database or email delivery

The important point is simple:

bootstrap creates the repo contract
provider accounts, domains, and credentials are still real-world prerequisites

2. Which Provider Is For What

The default GoingNinja stack currently assumes these roles:

Need	Typical provider role
source control and repository hosting	GitHub
runtime hosting for the product app	Vercel
persistent database	Neon
DNS, Access, or Pages for protected manuals and static surfaces	Cloudflare
email or OTP delivery	product-specific provider chosen by the requirement set

Not every product needs every provider on day one.

Examples:

a public reading slice may need GitHub and Vercel first, but not Cloudflare Access
a manual surface on Cloudflare Pages needs Cloudflare, but not necessarily Vercel
a member login path needs an email or OTP provider before launch, but not before the first public-only slice

3. Sessions, Tokens, And Secrets

These words mean different things and should not be mixed together.

Type	What it is	Typical example
CLI session	a local authenticated login stored by the provider CLI	`gh auth login`, `vercel login`, `wrangler login`
API or access token	a string used by automation or headless commands	`GH_TOKEN`, `VERCEL_TOKEN`, `CLOUDFLARE_API_TOKEN`
project secret	a product-specific runtime secret used by the app itself	`SESSION_SECRET`, database URL, webhook secret

Plain rule:

provider sessions and tokens let you talk to GitHub, Vercel, or Cloudflare
project secrets let the product runtime operate safely

Do not use a project secret as if it were a provider token. Do not treat a provider token as if it were product state.

4. What Must Be Global vs Project-Local

GoingNinja separates provider access from product secrets.

Global provider scope should hold reusable provider access such as:

GitHub CLI session or token
Vercel token
Cloudflare API token
Neon API key

Project-local secret scope should hold only product-specific runtime values such as:

session secret
product database URL
webhook secret
mail provider key that belongs only to that product

This is why a fresh repo can tell you what it needs without storing the actual values in Git.

5. Zero-To-Start Sequence

For a newcomer, the clean sequence is:

create or identify the GitHub owner that will hold the product repo
authenticate GitHub locally with gh auth login
create or identify the deployment owner, such as a Vercel account or team
authenticate the deployment CLI or create the required access token
decide whether the product needs a domain immediately or only a preview host first
reserve the pre-launch preview host, which defaults to www.preview.<product-domain>
if Cloudflare will own DNS, Pages, or Access, create the account and API token before those steps are needed
confirm the Product Brief
bootstrap the product repo from goingninja-os
fill REQUIREMENTS, ARCHITECTURE_REQUIREMENTS, and READINESS_GATE
only then plan, build, deploy, and audit

That order matters because the repo contract and the provider setup solve different problems.

6. Branches And Pipelines Baseline

Before machines can work safely, the repo needs a simple branch and automation model.

The minimum GoingNinja baseline is:

main is the continuity branch
feature work happens before merge
deterministic checks run on pull requests
rendered state views are rewritten only after merge on main

In a generated project repo, that usually means:

.github/workflows/pr-audit.yml for pre-merge checks and review lanes
.github/workflows/post-merge-state.yml for post-merge rendering on main

This is what turns “the tools ran once on my machine” into a repeatable repo path.

7. Preview Domains And Deploy Surfaces

Preview and live are different things.

The beginner-safe rule is:

local preview proves the slice can render
hosted preview proves the provider and Access contract works
live domain proves the public launch boundary

Examples:

Vercel generates deployment preview URLs under Vercel-owned domains before a custom domain is attached
Cloudflare Pages generates preview URLs for static surfaces
GoingNinja treats www.preview.<product-domain> as the canonical pre-launch hosted preview for product surfaces
custom domains come only after the preview surface is already coherent

For hosted product previews, the default rule is:

publish the current pre-launch continuity state on www.preview.<product-domain>
put that hostname behind Cloudflare Access
keep the raw provider hostname for debugging only, not as the canonical preview URL

That means a product may be locally proven before a hosted preview exists.

8. CLI Tools And Review Lanes

GoingNinja separates builder and reviewer roles.

Typical tool split today:

one agentic builder surface for scoped implementation work
Claude Code for the blocking architecture or contract review lane
Gemini CLI for the broad non-blocking risk lane

The important distinction is:

CLI version = the installed tool version
model selection = the provider-side model used by that tool or action

A repo may pin the action family or CLI path without pinning one exact model ID yet. That is acceptable only if the repo says so explicitly.

In the current Tagnova proof case, the committed workflow pins review lanes and action families, but not one exact Claude or Gemini model ID yet.

9. Billing And Ownership

Billing follows the provider that executes the work.

In practice:

GitHub Actions minutes are billed to the GitHub owner when private-repo runner usage exceeds the included quota
Claude review runs are billed to the Anthropic workspace or account behind ANTHROPIC_API_KEY
Gemini review runs are billed to the Google AI or Google Cloud billing context behind GEMINI_API_KEY
the hosted wiki assistant bills to the Mistral workspace behind the active MISTRAL_API_KEY
Vercel builds and hosted environments are billed to the Vercel account or team
Cloudflare DNS, Pages, or Access usage is billed to the Cloudflare account

This is why ownership must be clear before automation is turned on.

This page keeps billing at the owner-and-surface level. Exact prices and free tiers still belong to the current provider billing pages.

10. Minimum Beginner Checklist

If someone wants to start a fresh product with the current default stack, the minimum checklist is:

GitHub account or org available
gh installed and authenticated
Vercel account or team available
Vercel CLI available or VERCEL_TOKEN prepared
product domain plan decided
preview hostname www.preview.<product-domain> reserved in that plan
DNS owner known
Cloudflare account available if DNS, Pages, or Access should live there
preview Access allowlist ownership known before hosted preview is turned on
confirmed Product Brief before any product-specific build work