docs(billing): add org KiloClaw billing specs

.specs/template.md

@@ -2,54 +2,45 @@
 
 ## Role of This Document
 
-This spec defines the business rules and invariants for [feature].
-It is the source of truth for _what_ the system must guarantee —
-valid states, ownership boundaries, correctness properties, and
-user-facing behavior. It deliberately does not prescribe _how_ to
-implement those guarantees: handler names, column layouts,
-conflict-resolution strategies, and other implementation choices
-belong in plan documents and code, not here.
+This spec defines [feature] business rules and invariants: valid states, ownership boundaries, correctness properties,
+and user-facing behavior. It is the source of truth for _what_ the system must guarantee, not _how_ to implement it.
+Handler names, column layouts, conflict-resolution strategies, and other implementation choices belong in plans and code.
 
 ## Status
 
 Draft -- created YYYY-MM-DD.
 
 ## Conventions
 
-The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
-"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
-"OPTIONAL" in this document are to be interpreted as described in
-BCP 14 [RFC 2119] [RFC 8174] when, and only when, they appear in all
-capitals, as shown here.
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT
+RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC 2119] [RFC 8174]
+when, and only when, they appear in all capitals, as shown here.
 
 ## Definitions
 
-- **Term**: Definition of a domain-specific term used throughout
-  this spec.
+- **Term**: Domain-specific term definition used throughout this spec.
 
 ## Overview
 
-A concise narrative (1-2 paragraphs) describing the feature from a
-user and system perspective. Cover what the feature does, who it
-serves, and the high-level lifecycle. Avoid implementation details.
+Concise narrative (1-2 paragraphs) describing the feature from user and system perspectives. Cover what the feature
+does, audience, and high-level lifecycle. Avoid implementation details.
 
 ## Rules
 
 ### [Section Name]
 
-1. The system MUST ...
-2. The system MUST NOT ...
+1. System MUST ...
+2. System MUST NOT ...
 
 ## Error Handling
 
-1. When [error condition], the system MUST [behavior].
+1. When [error condition], system MUST [behavior].
 
 ## Not Yet Implemented
 
-The following rules use SHOULD and reflect intended behavior that is
-not yet enforced in the current codebase:
+Intended SHOULD rules not yet enforced in the current codebase:
 
-1. The system SHOULD ... (Currently ...)
+1. System SHOULD ... (Currently ...)
 
 ## Changelog
 

PRODUCT.md

@@ -0,0 +1,57 @@
+# Product
+
+## Register
+
+product
+
+## Users
+
+Kilo Cloud serves developers, team and organization admins, and internal operators who use or manage Kilo Code across editor, command line, and cloud workflows. Users are technical, time-constrained, and often switching between code, billing, integrations, security, deployment, and agent-session management.
+
+Their job is to keep Kilo usage understandable and operational: manage Kilo Organizations, seats, credits, plans, model access, billing, integrations, Cloud Agents, Kilo Deploy, Code Reviews, Managed Indexing, Security Agent, Auto Triage, Kilo Autofix, App Builder, and KiloClaw infrastructure.
+
+## Product Purpose
+
+Kilo Cloud is the operational surface around Kilo Code, the open-source AI coding agent. It gives users one place to manage AI usage, model inference, Kilo Credits, paid plans, organizations, integrations, cloud-based agents, deployment automation, code review automation, security workflows, indexing, and infrastructure lifecycle tasks.
+
+Success means users can quickly understand what is running, what it costs, who has access, what needs attention, and what action to take next. The interface should reduce uncertainty, not decorate it.
+
+## Brand Personality
+
+Expert, direct, utilitarian, transparent, and human. Write conversationally, like talking to a fellow developer. Use first-person and second-person naturally where helpful. Be enthusiastic about what Kilo is building, but avoid hype.
+
+The product voice should feel like a technical teammate who has done the work: precise, candid, useful, and willing to explain complexity without talking down to the user.
+
+Avoid robotic, generic, or AI-generated prose. Do not start messages with filler such as “Great,” “Certainly,” “Okay,” or “Sure.” Avoid marketing jargon and hype words such as “revolutionary,” “game-changing,” and “synergy.”
+
+## Anti-references
+
+Do not look or sound like a generic SaaS dashboard, neon AI hype product, decorative glass or gradient-heavy interface, playful consumer app, corporate enterprise portal, or vague marketing site.
+
+Avoid these product and content patterns:
+
+1. Blue-primary SaaS chrome when Kilo yellow-green should carry the primary action.
+2. Decorative gradients, glassmorphism, and AI-themed glow effects outside the rare agent-surface glow described in DESIGN.md.
+3. Repeated same-sized card grids with icon, heading, and text.
+4. Big-number hero metric sections that feel like template SaaS marketing.
+5. Buzzword copy that claims value instead of showing the concrete workflow impact.
+6. Ambiguous billing language. Use Kilo Credits for purchased usage credit. Reserve “token” for model input and output volume only.
+7. Old naming patterns such as “Kilo For Teams,” “Kilo for Enterprise,” “Kilo for Organizations,” “Kilo Code Deploy,” “Kilo Managed Indexing,” or “Kilo Cloud Agents.”
+
+## Design Principles
+
+1. **Utility before atmosphere.** Every screen should help the user decide what is happening, what matters, and what to do next. Visual style supports operational clarity.
+2. **Show the work.** Prefer concrete costs, states, timestamps, links, examples, and next actions over abstract reassurance.
+3. **Treat developers as peers.** Assume intelligence, explain context when needed, define niche concepts when introduced, and avoid performative simplicity.
+4. **Keep the brand action scarce.** Kilo yellow-green is the primary action and brand signal. Use it with intent so it retains meaning.
+5. **Be precise with naming and billing language.** Use product names consistently: Kilo, Kilo CLI, Kilo Plans, Kilo Teams, Kilo Enterprise, Kilo Deploy, Cloud Agents, Parallel Agents, Code Reviews, App Builder, Managed Indexing, Security Agent, Auto Triage, Kilo Autofix, and iOS App. Use paid plans for Teams and Enterprise collectively. Use Kilo Organization for the place where seats and credits are managed.
+
+## Accessibility & Inclusion
+
+Target WCAG AA. Prioritize keyboard navigation, visible focus states, readable dense data, sufficient contrast, reduced-motion-safe animations, and clear error recovery.
+
+Use sentence case for user-visible product chrome. Avoid all caps except intentional eyebrow labels and rare role badges already defined by the design system. Avoid acronyms when possible; when acronyms are needed, expand them at least once in a conversation or document.
+
+For timestamps and deadlines, account for distributed teams. Prefer exact dates, relative times, and timezone references over ambiguous phrases such as “end of day.” For internal content, use ISO dates in `yyyy-mm-dd` format and months in `yyyy-mm` format.
+
+Use `open source` as a noun and `open-source` as an adjective before a noun. Refer to Kilo Code people as Kilo Code team members, not employees. Use “non-US” instead of “international,” “offshore,” or “overseas” when referring to team members outside the US.