Skip to content

Open source CapCut alternative.

TypeScript

docs: describe su-edited state without the su app

David Le3f66a34d033e
diff --git a/AGENTS.md b/AGENTS.md
index ce6b13a0..651e3066 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -63,7 +63,7 @@ Every Cut change has to hold on every surface, and the plan for it says how:
- Prefer deleting over documenting what was removed. Guides describe what is supported now, not what used to be.
- Build forward by default. Prefer updating callers and contracts to the new supported shape instead of preserving old compatibility paths; ask before adding or keeping backwards-compatibility shims.
- GPT and Claude model updates include retirement. Verify provider availability and lifecycle in official docs; retire superseded picker entries when a supported successor covers their role, retaining distinct capability or cost tiers. Distinguish Donkey retirement from provider deprecation. Update callers and defaults, migrate saved selections to explicit replacements within the same provider, and preserve chat history. Verify new selections and resumed chats in the same change.
-- Configuration is code with a runtime override. Tunables, switches and thresholds are declared in the settings registry (`site/src/lib/config/registry.ts`) with a default and a schema, overridden from su, and read through it everywhere; env is for secrets. An experiment is variants over settings, drawn by an audience; a feature that people might tune ships its setting in the same change.
+- Configuration is code with a runtime override. Tunables, switches and thresholds are declared in the settings registry (`site/src/lib/config/registry.ts`) with a default and a schema, overridden in the database, and read through it everywhere; env is for secrets. An experiment is variants over settings, drawn by an audience; a feature that people might tune ships its setting in the same change.
- Fail hard. One provider, one model, one code path per job; a missing API key, service, or capability is an error surfaced to the caller. No secondary providers, no retry-on-another-model paths, no `env.X || default` softening. A fallback exists only when it is absolutely necessary — a surface that genuinely cannot carry the feature — and the summary and the guide say so.
- After finishing a task, summarize what you did. Ground the summary in the actual code changes — name the files and behavior that changed, not the intent you set out with. If nothing changed, say so. When the change has a shape worth seeing — a system flow or a UI layout — include a small ASCII diagram of it.
- This is an open source project. Stay alert for security concerns, and never commit PII, API keys, tokens, credentials, private config, or other secrets.
diff --git a/CLAUDE.md b/CLAUDE.md
index 256f51ab..75eec753 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -64,7 +64,7 @@ Every Cut change has to hold on every surface, and the plan for it says how:
- Prefer deleting over documenting what was removed. Guides describe what is supported now, not what used to be.
- Build forward by default. Prefer updating callers and contracts to the new supported shape instead of preserving old compatibility paths; ask before adding or keeping backwards-compatibility shims.
- GPT and Claude model updates include retirement. Verify provider availability and lifecycle in official docs; retire superseded picker entries when a supported successor covers their role, retaining distinct capability or cost tiers. Distinguish Donkey retirement from provider deprecation. Update callers and defaults, migrate saved selections to explicit replacements within the same provider, and preserve chat history. Verify new selections and resumed chats in the same change.
-- Configuration is code with a runtime override. Tunables, switches and thresholds are declared in the settings registry (`site/src/lib/config/registry.ts`) with a default and a schema, overridden from su, and read through it everywhere; env is for secrets. An experiment is variants over settings, drawn by an audience; a feature that people might tune ships its setting in the same change.
+- Configuration is code with a runtime override. Tunables, switches and thresholds are declared in the settings registry (`site/src/lib/config/registry.ts`) with a default and a schema, overridden in the database, and read through it everywhere; env is for secrets. An experiment is variants over settings, drawn by an audience; a feature that people might tune ships its setting in the same change.
- Fail hard. One provider, one model, one code path per job; a missing API key, service, or capability is an error surfaced to the caller. No secondary providers, no retry-on-another-model paths, no `env.X || default` softening. A fallback exists only when it is absolutely necessary — a surface that genuinely cannot carry the feature — and the summary and the guide say so.
- After finishing a task, summarize what you did. Ground the summary in the actual code changes — name the files and behavior that changed, not the intent you set out with. If nothing changed, say so. When the change has a shape worth seeing — a system flow or a UI layout — include a small ASCII diagram of it.
- This is an open source project. Stay alert for security concerns, and never commit PII, API keys, tokens, credentials, private config, or other secrets.
diff --git a/docs/guides/backend-apis.md b/docs/guides/backend-apis.md
index d2b4a0e1..b6b21642 100644
--- a/docs/guides/backend-apis.md
+++ b/docs/guides/backend-apis.md
@@ -156,7 +156,7 @@ balance short of one flat-priced generation also returns the price it could not
cover, and that account can still run chat and the other metered calls, so a
client knows to keep the rest of the surface working.
-Credit given by hand is an offer su emails as a claim link; the grant and its
+Credit given by hand is an offer emailed as a claim link; the grant and its
ledger entry are written when the person claims, with the credit's lifetime
counted from that moment.
diff --git a/docs/guides/blog.md b/docs/guides/blog.md
index e269e945..1de27e40 100644
--- a/docs/guides/blog.md
+++ b/docs/guides/blog.md
@@ -3,8 +3,7 @@
donkeycut.com/blog is the site's writing surface for search: an index of posts,
one page per post, and a sitemap that lists them. The words and images of a
post live outside the repository. A post's row is in Postgres, its article is
-an MDX file in the private bucket, and its images sit beside that file. Posts
-are written in su, an internal app in a private repo.
+an MDX file in the private bucket, and its images sit beside that file.
**The one rule:** the repository holds the layout and the machinery; the
content lives in the database and the bucket. A post reaches the site through
@@ -13,11 +12,11 @@ the cache.
## How a post reaches the page
```text
-su: write, save, publish
+internal admin app: write, save, publish
│
▼
row in Postgres · blog/<id>/article.mdx and blog/<id>/<sha>.avif in the bucket
- │ su calls the revalidate route, which clears the `blog` and `blog:<slug>` tags
+ │ POST /api/blog/revalidate (BLOG_REVALIDATE_SECRET) clears `blog` and `blog:<slug>`
▼
/blog and /blog/<slug> read through `use cache` and compile the MDX inside it
│
@@ -50,9 +49,9 @@ source stays private.
## Previewing a draft
-Preview is Draft Mode. su's Preview button opens a route on donkeycut.com that
-turns Draft Mode on for that browser and lands on the post's real address. With
-the cookie set, the blog's cached reads run fresh and include drafts for that
+Preview is Draft Mode. A super user opening the preview route on donkeycut.com
+turns it on for that browser and lands on the post's real address. With the
+cookie set, the blog's cached reads run fresh and include drafts for that
browser alone; every other visitor keeps the cache. A banner on the previewed
page leaves Draft Mode.
diff --git a/docs/guides/chatgpt-app.md b/docs/guides/chatgpt-app.md
index ea3a45f5..5e39de52 100644
--- a/docs/guides/chatgpt-app.md
+++ b/docs/guides/chatgpt-app.md
@@ -85,8 +85,8 @@ already issued media links valid until their normal expiry.
The integration defaults to disabled in the `chatgptApp` setting. Deploy the
Prisma models in `site/prisma/Chatgpt.prisma` through the project's database
-release process, deploy the site and cloud worker, then enable the setting in
-su.
+release process, deploy the site and cloud worker, then turn the setting
+on.
Set the same `CUT_RUNNER_SECRET` on the hosted site and the
`donkey-cut-worker` Cloudflare Worker before deployment. The Worker passes it
diff --git a/docs/guides/config-and-experiments.md b/docs/guides/config-and-experiments.md
index a0027e61..79f089f4 100644
--- a/docs/guides/config-and-experiments.md
+++ b/docs/guides/config-and-experiments.md
@@ -5,15 +5,13 @@ varies what they get, and reads its own result. A fork runs the same work with
its own numbers, and none of it needs a deploy to change.
**The one rule:** configuration is code with a runtime override. Every tunable
-is declared once in the settings registry with a default and a schema; a super
-user edits the override on su.donkeycut.com; env holds secrets and nothing
-else. An experiment is a set of variants over settings, drawn by an audience.
+is declared once in the settings registry with a default and a schema, and
+overridden by a database row; env holds secrets and nothing else. An experiment is a set of variants over settings, drawn by an audience.
## Settings
The registry is one file that lists every setting the product has. Each entry
-carries a schema, a default, a title and description for the su form, and
-whether the value is public. A public setting reaches the browser through the
+carries a schema, a default, a title, a description, and whether the value is public. A public setting reaches the browser through the
account config route; a server setting is read only by handlers, webhooks and
jobs.
@@ -23,7 +21,7 @@ A value resolves in three layers, later ones winning:
default (code)
│
▼
-override (SettingOverride row, edited on su)
+override (SettingOverride row)
│
▼
variant (the experiment the account is assigned to)
@@ -31,9 +29,8 @@ variant (the experiment the account is assigned to)
The registry parses every default against its schema when the module loads,
so a wrong default fails the process at boot. A stored override that no longer
-parses after a schema change is skipped, logged, and shown on su as invalid so
-it can be reset. su is an internal app in a private repo; the overrides it
-writes live in the database.
+parses after a schema change is skipped and logged. An internal admin app
+writes overrides, experiments and promotions.
**Every tunable is a setting.** A threshold, a switch, a mode: if an operator
might want it different, it is a registry entry, and a feature that people
@@ -95,9 +92,8 @@ stored on the assignment row, so a report can say where each cohort was.
### Overrides by account
-An account can be placed by hand. On su, an experiment takes an email and a
-variant, and that row stands in place of the hash from then on; the same form
-holds the account out of that one experiment. A holdout list, kept beside the
+An account can be placed by hand: a manual assignment row names a variant, or
+none to hold the account out, and stands in place of the hash. A holdout list, kept beside the
experiments, keeps an account out of every experiment: it is never assigned,
reads the plain configuration even where it holds a row, and never counts in a
result. Rows written by hand are never counted either.
@@ -108,8 +104,8 @@ A metric is something an exposed account does after its exposure: a PostHog
event by name, or a purchase recorded in the credit grants. An experiment
lists its metrics, and the first one decides the verdict.
-A nightly job computes each live experiment's read and stores it on the row;
-su shows it, with a button to compute one experiment now. For every metric
+A nightly job computes each live experiment's read and stores it on the row.
+For every metric
and variant it counts exposed accounts and how many converted, then compares
each variant to the control two ways: a classical two-proportion test for the
p-value, and a Beta-Binomial posterior for the chance the variant beats the
@@ -129,32 +125,29 @@ by variant as well.
## Promotions
-A promotion is one email from su to an audience, minus anyone an earlier promotion reached; the Pro offers behind it (subscribe bonus, allowance multiplier) are Product-tab settings. A draft saves however it stands and is checked whole at a test or a send. The Outreach tab sends a promotion to one person by hand, as the same email under the same per-person outbox key, so it counts in the promotion and a later segment send skips them.
+A promotion is one email to an audience, minus anyone an earlier promotion reached; the Pro offers behind it (subscribe bonus, allowance multiplier) are settings. A copy sent to one person by hand carries the same per-person outbox key, so it counts in the promotion and a later segment send skips them.
Every outbound email is a row in one outbox, sent by one drainer in priority order under the email plan's monthly allowance, shared by the whole site. A promotion is read from the accounts table a page at a time by a job, queues its most recently active recipients first, and stops at what the rest of the billing cycle is forecast to need for welcome and credit emails, and for mail sent by hand on the work days left, then picks up the slots that go unused as the cycle runs down. The allowance, the renewal day, the reserves and the work hours are the Email send budget setting, and the order between kinds is the Email priorities setting.
A credit promotion is a credit offer: one row that promises an account an
amount, the credit's life, and the window it can be claimed in, then records
the grant that lands. Every kind shares that row, and a kind is a setting and
-code: what opens the offer and what claims it. The manual credit su sends by
-email is one kind, and its link closes a few days after the send, a Product-tab
-setting; the subscribe bonus, offered when an account has spent a
+code: what opens the offer and what claims it. A manual credit sent by email
+is one kind, and its link closes a few days after the send; the subscribe bonus, offered when an account has spent a
share of its signup grant and landed by a Pro subscription created inside the
window, is another. A promotion's offer is landed by its link or, when the
promotion says so, by a Pro subscription started inside the window; a checkout
carries the largest open offer of that kind, so one lands per subscription.
-An outreach note to one person carries the same offer terms, from the same
-form and the same templates, and the Outreach tab takes an account by its
-address so a note can go to anyone. A new promotion adds no table.
+An outreach note to one person carries the same offer terms. A new promotion
+adds no table.
## Verification
The registry, audience, assignment, experiment schema, statistics and verdict
-are pure and covered by unit tests. On a dev server: create an experiment on
-su with two variants and a metric and start it, load the app as two accounts
-and confirm the assignment rows and the exposure event; place one account by
-hand and confirm it reads that variant; hold an account out and confirm it
-reads the plain configuration; compute results and confirm the verdict reads
-too early.
+are pure and covered by unit tests. On a dev server, with an experiment of two
+variants and a metric running, load the app as two accounts and confirm the
+assignment rows and the exposure event; confirm a hand-placed account reads
+its variant, a held-out account reads the plain configuration, and the results
+job reads too early.
## Source Map