Monetization tiers: Free / Pro / Teams

[kpmmmurphy]

The shape

Three tiers, discussed 2026-09-17:

Tier	What	Who pays	Why they pay
Free	Full M1K3 — brain, knowledge graph, memory, voice, privacy	Nobody	The promise. The trust. The moat.
Pro	Cosmetic + delight: extra avatars, voice packs, companion skins	Individuals	They love it and want to dress it up
Teams	Custom App via ASC, stripped to business, org knowledge graph, managed deployment, branded	IT departments	On-prem AI that never phones home

The rule (structural, not a preference)

Pro never gates intelligence, memory, or privacy. Only aesthetics. Write it into the code the way the consent gates are written — a policy, not a preference.

"Free for humans" stays literally true

Pro is "free for humans, fancy for fans." The core promise is the brand.

Open questions

• Who's the first Teams customer? (Kev: the next 90 days of LinkedIn)
• Pro: RevenueCat (Lexy's pipeline) or StoreKit 2 native?
• Pro: which avatars/voices are free vs Pro? (all current ones could be free, Pro = future additions)
• Teams: Custom App record (Public→Private locked at first approval, Teams: the PCC policy key must read the FORCED value, not UserDefaults.standard #350)
• Teams: the policy-key forced-value read (Teams: the PCC policy key must read the FORCED value, not UserDefaults.standard #350) must work before deployment
• ADR needed before implementation

Context

• FSL-1.1-ALv2 licence already supports the structure (chore(license): relicense forward to FSL-1.1-ALv2 — free for humans, source-available, organisations are the paid line #259)
• /teams page exists as positioning
• Lexy's institutional buy ≈ 100× consumer ASO — enterprise is where the money is
• No server costs per user (on-device) means free tier is sustainable

Ref: session 2026-09-17 discussion

[kpmmmurphy]

A spike on where the "cosmetic, never capability" line actually falls in the code (jam, 2026-09-18). The repo gitignores macos/scratch/**, so the write-up lives here. The sketch below runs as a script (swift CosmeticGate.swift) and its nine checks pass; the negative claim was verified with swiftc -typecheck (requires that 'BrainTier' conform to 'Cosmetic').

1 · The picker is not the gate

Today the renderer resolves the stored raw value directly:

M1K3App/CompanionAvatarView.swift:214   CompanionShadingStyle(rawValue: shadingRaw) ?? .off
M1K3App/CompanionSettings.swift:72      Picker("Skin", selection: $companionShading)
M1K3App/CompanionSettings.swift:110     Picker("Face", selection: $voiceCompanion)

A lock on the picker row is decoration. defaults write, or the launch argument the
screengrab harness already passes (-companion.shadingStyle off), writes the value the
renderer reads. An entitlement has to resolve at the render seam — stored value in,
effective value out — and the picker merely shows what that seam would allow.

2 · Make the rule a type

The 09-17 rule — Pro never gates intelligence, memory, or privacy; only aesthetics — is a
sentence in an issue. Sentences drift (this project's own soul review: it held where it was
structural and drifted only where it was copy). So:

• protocol Cosmetic — only look-and-sound enums conform (CompanionShadingStyle, the
  companion ids, a voice timbre, an accent palette).
• CosmeticGate.resolve/isAvailable accept only Cosmetic.
• Gating a BrainTier then does not compile (verified:
  requires that 'BrainTier' conform to 'Cosmetic'). Making a capability purchasable would
  take someone writing : Cosmetic on it in a PR — visible, reviewable, refusable.

3 · Lapse is silent and keeps the choice

Un-owned Pro value → the type's freeDefault at render. The stored choice is kept, so a
restore/re-purchase brings the skin back without re-picking. No nag, no broken avatar, no
"your subscription expired" anywhere near the chat. Each freeDefault must itself be free,
and every cosmetic type needs a free option — two invariants worth real tests on promotion.

4 · ★ RevenueCat conflicts with the privacy page

The 09-17 plan says "Pro is RevenueCat territory (Lexy's pipeline)". For Lexy that is right.
For M1K3 it collides with the product's central claim:

• site/privacy.html lists the complete set of network crossings, all user-initiated, and
  says no account, no telemetry.
• RevenueCat's SDK talks to RevenueCat's servers and mints an app-user id (anonymous by
  default, but an identifier) to do it. That is a third-party crossing the user did not
  initiate, plus an identifier — the two things the page says do not exist.
• StoreKit 2 alone is enough here: Transaction.currentEntitlements is verified on
  device; a purchase talks to Apple, user-initiated, over the same channel the App Store copy
  already uses for install and updates. One honest new line on the privacy page
  ("buying Pro talks to Apple") instead of a rewritten promise.
• What RevenueCat would have bought — cross-platform entitlements, server receipts, paywall
  experiments, charts — is what M1K3 should not want: there is no account to attach them to.

Confidence 0.8 on the conflict (RevenueCat's network behaviour is from general knowledge, not
re-read today — confirm against their current SDK docs before deciding). Kev's call.

5 · Which knobs are cosmetic today

Knob	Where	Cosmetic?
Skin (CompanionShadingStyle: off · phosphor · cel)	M1K3Avatar	yes — pure surface
Face (companion creature / pixel face / constellation)	CompanionSpec	yes — but the house Phosphor Fox stays free: it is the brand, and the fallback
Voice timbre (Kokoro voices)	M1K3Kokoro	mostly — ⚠️ M1K3 Voice vs system voice is accessibility, not cosmetic; reading aloud is a dyslexia feature. Timbres within it could be Pro; having a good voice at all cannot
Reading modes (bionic, OpenDyslexic, karaoke)	ReadingMode	NO — accessibility. Never gated.
Notch HUD, screensaver, menu-bar pet	app	presence features, not skins — leave free; they are the product's charm and its marketing
Brain tier, tools, memory, MCP, Brain at Home, PCC	—	capability — cannot conform

The two "mostly/NO" rows are where a careless Pro tier would hurt real people. The type rule
helps only if nobody marks ReadingMode: Cosmetic — so the promotion PR should add a test
that enumerates the conforming types and pins the list.

6 · If promoted

1. Cosmetic + CosmeticGate into M1K3Avatar (pure, TDD) with the two invariants + the
   pinned list of conforming types.
2. The render seam: CompanionAvatarView and the voice-mode companion resolve through the
   gate. Screengrab harness passes an Entitlements(ownsPro: true) so plates can show Pro art.
3. EntitlementStore over StoreKit 2, injected; a fake for tests and -pro.fake YES for dev
   builds only (#if DEBUG).
4. Only then: the first paid skin, the locked picker row, the privacy-page line.
5. Teams (Custom App) builds ship with ownsPro: true and no store UI at all.

CosmeticGate.swift — the runnable sketch

#!/usr/bin/env swift
//
//  CosmeticGate.swift — SPIKE (scratch/, untested by design; run it: `swift CosmeticGate.swift`)
//
//  Question (#369): what does "Pro = cosmetics, never capability" look like as a SEAM?
//  Answer this file argues for: make the rule a TYPE, and resolve it at the RENDER
//  seam, not at the picker.
//
//  1. `Cosmetic` is a protocol only cosmetic enums conform to. `CosmeticGate` accepts
//     nothing else — so "gate a brain tier behind Pro" does not compile. The 09-17
//     rule ("Pro never gates intelligence, memory, or privacy") stops being a sentence
//     in an issue and becomes something the compiler refuses.
//  2. The gate RESOLVES a stored raw value into an effective one. Today the renderer
//     does `CompanionShadingStyle(rawValue: stored) ?? .off` (CompanionAvatarView:214),
//     so a picker-only lock is decoration: `defaults write`, or the very launch argument
//     the screengrab harness uses (`-companion.shadingStyle cel`), walks past it.
//  3. Lapse is graceful and silent: an un-owned Pro value falls back to the type's free
//     default. Nothing breaks, nothing nags, the stored choice is KEPT (so re-buying
//     restores it without the user re-picking).
//
//  Signed: Kev + claude-fable-5.1, 2026-09-18, Confidence 0.6 (a spike: it compiles and
//  its asserts pass; none of it is wired to the app). Prior: none (new file).
//

import Foundation

// MARK: - The rule, as types

enum CosmeticTier { case free, pro }

/// Only things that change how M1K3 LOOKS or SOUNDS conform. There is deliberately no
/// way to make `BrainTier`, a tool, or a memory feature conform without writing the
/// words `: Cosmetic` on it in a PR someone has to approve.
protocol Cosmetic: RawRepresentable, CaseIterable where RawValue == String {
    var tier: CosmeticTier { get }
    /// What an un-owned Pro choice falls back to. Must itself be `.free`.
    static var freeDefault: Self { get }
}

/// What the device knows it owns. In the real thing this is filled from StoreKit 2's
/// `Transaction.currentEntitlements` — verified ON DEVICE, no server of ours, no SDK
/// that phones home. (See FINDINGS.md: that is the reason NOT to use RevenueCat here.)
struct Entitlements: Equatable {
    var ownsPro: Bool
    static let none = Entitlements(ownsPro: false)
}

enum CosmeticGate {
    /// The RENDER seam: stored raw value → what may actually be drawn.
    static func resolve<C: Cosmetic>(_: C.Type = C.self, stored: String, owning: Entitlements) -> C {
        guard let chosen = C(rawValue: stored) else { return C.freeDefault }
        return isAvailable(chosen, owning: owning) ? chosen : C.freeDefault
    }

    /// The PICKER seam: may this row be selected, or does it show a lock?
    static func isAvailable(_ item: some Cosmetic, owning: Entitlements) -> Bool {
        item.tier == .free || owning.ownsPro
    }
}

// MARK: - What would conform (mirrors of the real enums, reduced)

enum ShadingStyle: String, Cosmetic {
    case off, phosphor, cel, aurora // `aurora` is the imaginary paid skin

    var tier: CosmeticTier {
        self == .aurora ? .pro : .free
    }

    static var freeDefault: ShadingStyle {
        .off
    }
}

enum CompanionID: String, Cosmetic {
    case phosphorFox = "PhosphorFox", fox = "Fox", gecko = "Gecko", owl = "Owl" // `owl`: imaginary paid creature

    var tier: CosmeticTier {
        self == .owl ? .pro : .free
    }

    static var freeDefault: CompanionID {
        .phosphorFox
    }
}

/// The line, demonstrated: this is NOT cosmetic and cannot be gated.
enum BrainTier: String, CaseIterable { case mini, lil, big }
// CosmeticGate.resolve(BrainTier.self, stored: "big", owning: .none)
//   → error: type 'BrainTier' does not conform to protocol 'Cosmetic'   ← the point

// MARK: - Run it

func check(_ condition: @autoclosure () -> Bool, _ label: String) {
    print(condition() ? "  ✓ \(label)" : "  ✗ \(label)")
    if !condition() { exit(1) }
}

let pro = Entitlements(ownsPro: true)
print("render seam")
check(CosmeticGate.resolve(ShadingStyle.self, stored: "cel", owning: .none) == .cel, "a free skin renders for everyone")
check(CosmeticGate.resolve(ShadingStyle.self, stored: "aurora", owning: pro) == .aurora, "a Pro skin renders when owned")
check(
    CosmeticGate.resolve(ShadingStyle.self, stored: "aurora", owning: .none) == .off,
    "a Pro skin written straight into defaults falls back — the picker was never the gate"
)
check(CosmeticGate.resolve(ShadingStyle.self, stored: "garbage", owning: pro) == .off, "an unknown value falls back")
check(CosmeticGate.resolve(CompanionID.self, stored: "Owl", owning: .none) == .phosphorFox, "un-owned creature → the house fox")
print("picker seam")
check(!CosmeticGate.isAvailable(ShadingStyle.aurora, owning: .none), "locked row when not owned")
check(CosmeticGate.isAvailable(ShadingStyle.aurora, owning: pro), "selectable when owned")
print("invariants worth a real test if this is promoted")
check(ShadingStyle.freeDefault.tier == .free && CompanionID.freeDefault.tier == .free, "every freeDefault is itself free")
check(ShadingStyle.allCases.contains { $0.tier == .free }, "every cosmetic type has a free option")
print("ok")