V2 -> Main

.agents/DESIGN.md

@@ -0,0 +1,187 @@
+# CallIt Design Standards
+
+CallIt should feel like a serious prediction finance product: a Pro-grade terminal that stays legible and calm under dense data.
+
+## Product Positioning
+
+CallIt is the consumer app for DeepBook Predict.
+
+The UI should communicate:
+
+- call market outcomes
+- risk a fixed premium
+- understand potential payout
+- track settlement and claims later
+- stay honest about oracle-based settlement
+
+The first UI focus is Trade. Portfolio, Earn, Risk, and Automate can appear in navigation, but Trade drives the first product experience.
+
+## Visual Direction
+
+Use a dark, finance-native visual system.
+
+The product should feel:
+
+- sharp
+- credible
+- high-signal
+- calm under dense data
+- more polished than a generic DeFi dashboard
+
+Avoid:
+
+- generic AI SaaS gradients
+- random accent colors
+- inconsistent one-off cards
+- playful visuals that weaken financial trust
+- density for its own sake: dense data must stay scannable
+
+## Shared Design System
+
+Every surface (Trade, Arena, Earn, Strategies, Keeper) must clearly belong to the same app.
+
+Shared system traits:
+
+- dark graphite or blue-black foundation
+- subtle grid or market texture where appropriate
+- thin borders with clear contrast
+- `rounded-md` as the default radius for bordered surfaces and controls
+- layered panels with controlled depth
+- cyan active and focus states
+- green payout/live accents
+- amber simulated or caution states
+- coral risk/loss states
+- muted secondary text
+- tabular numeric values
+- crisp spacing and alignment
+
+Use a small set of repeatable primitives for panels, badges, metrics, controls, tables, callouts, and status indicators. Do not create isolated component styles that cannot be reused.
+
+## Trade (Pro terminal)
+
+Trade is a terminal-style trading surface. It is the only trade mode; there is no Simple/Yes-No mode and copy must not promise one.
+
+The terminal should be:
+
+- compact
+- table-driven
+- optimized for scanning strikes and expiries
+- precise about market structure
+- clear about quote and settlement state
+
+The terminal can show:
+
+- asset strip
+- expiry selector
+- market table
+- order ticket
+- payoff preview
+- protocol context
+- oracle status
+- quote asset
+- abbreviated Predict object
+
+Terminal language should include:
+
+- `Up`
+- `Down`
+- `Range`
+- `Strike`
+- `Expiry`
+- `Premium`
+- `Potential payout`
+- `Oracle status`
+
+Use `Premium` (not `Risk`) for the amount at stake.
+
+Do not display payout multiplier yet unless the product decision changes.
+
+## Settlement Copy
+
+Settlement language must be accurate.
+
+For directional markets:
+
+```text
+Up wins above the strike.
+Down wins at or below the strike.
+```
+
+For range markets:
+
+```text
+Range wins if settlement finishes inside the selected range.
+```
+
+Never simplify `Down` to only `below` when the protocol semantics are `at or below`.
+
+## Navigation Direction
+
+Navigation should be simple and product-led.
+
+Initial nav items:
+
+- Trade
+- Portfolio
+- Earn
+- Risk
+- Automate
+
+Rules:
+
+- Trade is active first.
+- Automate remains visible but secondary or marked as coming later.
+- Wallet connect can be static until wallet integration begins.
+- The testnet status should be visible but compact.
+- Use the shadcn Navigation Menu component for desktop navigation when appropriate.
+- Mobile navigation should be a simple collapsible area using shadcn Collapsible.
+- Route navigation through CallIt primitives/app-frame components rather than raw shadcn usage in page components.
+
+## Theming Direction
+
+Theme before full product UI.
+
+The first visual checkpoints should prove:
+
+- background quality
+- panel treatment
+- typography hierarchy
+- status colors
+- active control state
+- metric treatment
+- terminal control language
+
+Do not rush into the full trade page before these basics feel right.
+
+## Component Design Rules
+
+- Product components should use CallIt primitives.
+- Primitives should wrap shadcn/base-ui where appropriate.
+- Product components may import shadcn `components/ui/*` directly when no CallIt abstraction exists yet.
+- Do not manually create shadcn `components/ui/*` components.
+- Do not create primitive files that only re-export shadcn components.
+- Do not add one-off component styles that bypass the design system.
+- Keep visual variants explicit and controlled.
+- Every recurring visual pattern should become a primitive or composed reusable component.
+
+## Accessibility And Responsiveness
+
+- Keep text contrast high enough on dark backgrounds.
+- Preserve visible focus states.
+- Use semantic controls through shadcn/base-ui or accessible primitives.
+- Cards must work well on mobile.
+- Terminal tables may adapt into stacked rows on mobile.
+- Do not hide critical risk or settlement information on small screens.
+
+## Current Design Priority
+
+The immediate sequence is:
+
+1. Theme foundation.
+2. Primitive quality.
+3. Navigation/app frame.
+4. Terminal foundation.
+5. Market table and order ticket.
+6. Payoff and protocol context.
+
+Each step should be reviewable before the next step begins.

.agents/IMPLEMENTATION_STANDARDS.md

@@ -0,0 +1,100 @@
+# CallIt Implementation Standards
+
+This document captures project rules that agents and contributors must follow while building CallIt.
+
+## Core Build Philosophy
+
+- Build component by component.
+- Do not one-shot the full app UI.
+- Prefer small visual checkpoints over large, speculative page implementations.
+- Establish theme, primitives, navigation, and product surfaces in sequence.
+- Keep the route layer thin.
+- Keep product logic out of visual components where practical.
+- Avoid premature file trees that box the project into names before the design is validated.
+
+## Component Layering
+
+Use this layering model:
+
+```text
+shadcn/base-ui
+  -> CallIt primitives
+    -> product surface components
+      -> route/page composition
+```
+
+Rules:
+
+- `components/ui/*` is shadcn-generated territory only.
+- Do not manually create shadcn components.
+- If a shadcn component is needed, install it with `bunx shadcn@latest add ...`.
+- CallIt primitives may be authored by us, but they should wrap shadcn/base-ui components where appropriate.
+- Product components should consume CallIt primitives, not raw shadcn/base-ui directly.
+- Product components may import shadcn `components/ui/*` directly when no CallIt abstraction exists yet.
+- Avoid direct raw HTML element usage in product components where a primitive can reasonably exist.
+- Raw HTML elements are acceptable inside primitives when creating the design-system abstraction itself.
+- Do not create primitive files that only re-export shadcn components.
+- Create primitives only when adding CallIt-specific props, variants, styling, behavior, or composition.
+
+## TypeScript Rules
+
+- Do not use `any`.
+- Do not use lazy bailout types.
+- Avoid broad unknown records unless the value is genuinely unknown at an external boundary.
+- Do not define throwaway inline domain types inside components.
+- Use named enums, interfaces, discriminated unions, and helper functions where appropriate.
+- Keep domain types separate from UI props when the domain concept is reused.
+- Validate external data boundaries with schemas where practical.
+- Do not make UI components responsible for parsing untrusted API responses.
+
+## Data And State Rules
+
+- Static data should still be typed like real product data.
+- Static data should be shaped so it can later map to DeepBook Predict server responses.
+- Do not invent custom fetch/cache abstractions when TanStack Query fits.
+- Do not invent custom form state abstractions when TanStack Form fits.
+- Use Zod for validation where runtime validation is useful.
+- API response parsing and mapping should happen at a boundary before data reaches product components.
+
+## Design System Rules
+
+- The app must follow a proper design system.
+- Do not ship half-baked or inconsistent visual styles.
+- Do not add one-off class patterns inside product components when a primitive should exist.
+- Binary and Range trade shapes may have different density and layout, but must belong to the same visual system.
+- Use consistent panel, badge, metric, status, control, and table treatments.
+- Use `rounded-md` as the default radius for app components and bordered surfaces.
+- Use tabular numeric styling for financial values.
+- Preserve clear state language for live, simulated, warning, risk, selected, disabled, and inactive states.
+
+## Naming Rules
+
+- Do not use `shell` naming in folders, components, types, or product copy.
+- Prefer names that describe product responsibility, such as frame, navigation, prediction cards, terminal, payoff, protocol context, or trade page.
+- Do not lock in folder names before a component responsibility is real.
+
+## Product Rules
+
+- Trade is one terminal surface for DeepBook Predict.
+- Binary and Range are contract shapes, not user modes.
+- Trade uses terminal language such as `Up`, `Down`, `Range`, `Strike`, `Expiry`, `Premium`, `Leverage`, `Max loss`, and `Potential payout`.
+- Do not display payout multiplier yet.
+- Always show risk/max loss wherever a trade preview appears.
+- Always show potential payout wherever a trade preview appears.
+- Always include accurate settlement language where a trade preview appears.
+- Do not present premium exposure as borrowed margin; leverage must include accurate limited-recourse risk copy.
+- Do not make unconditional no-liquidation promises.
+- Keep `Automate` visible in navigation, but do not prioritize it in the first Trade UI pass.
+
+## Verification Rules
+
+After each meaningful batch:
+
+- Run typecheck.
+- Inspect for accidental `any` usage.
+- Inspect for accidental `shell` naming.
+- Confirm product components use CallIt primitives.
+- Confirm no manual shadcn `components/ui/*` files were created.
+- Confirm no copy promises a Simple/Yes-No trade mode.
+- Confirm no copy promises no liquidation globally.
+- Confirm multiplier is not displayed unless the product decision changes.

.agents/MOVE_API_GUIDELINES.md

@@ -0,0 +1,38 @@
+# Move API Guidelines
+
+These rules apply to CallIt Move packages in addition to the local Move skills.
+
+## Prefer Narrow Returns
+
+- Public functions should return composable resources, such as owner caps, payout coins, refund coins, or created objects.
+- Avoid wide tuple returns for internal bookkeeping. If a helper only returns fields so the caller can emit an event, prefer named getters on the object plus a narrow lifecycle helper.
+- Lifecycle helpers should mutate lifecycle state and return only values they uniquely produce, such as a timestamp or a custodied balance.
+- Use structs only when multiple returned values form a reusable domain concept. Do not create throwaway structs just to hide unnecessary data flow.
+
+## Enforce Before Emitting
+
+- Do not emit events or update product state based on user-supplied claims about external Predict actions.
+- Derive object IDs from object references inside the contract.
+- Emit financial lifecycle events only after the underlying Predict mint, redeem, supply, withdraw, or manager-balance change succeeds.
+
+## Keep Events Narrow
+
+- Events should be lifecycle or activity anchors, not denormalized snapshots of shared objects.
+- Prefer key object IDs, consumed capability IDs when relevant, actors for participant-only activity, timestamps, and realized transition amounts that are not otherwise stored on a product object.
+- Read static product terms, configuration, custody facts, lifecycle state, and metadata directly from shared objects through getters or object reads.
+- Do not duplicate vectors, metadata hashes, oracle terms, manager IDs, Predict IDs, or full policy/call fields in lifecycle events when the object already stores them.
+
+## Preserve PTB Composability
+
+- Return coins and capabilities instead of transferring them to `ctx.sender()` from public functions.
+- Keep `ctx: &mut TxContext` last and `Clock` immediately before `ctx`.
+- Keep package APIs honest about custody: policies may record PredictManager positions, but they do not own those positions unless they hold a transferable asset.
+
+## Use Native Authority Objects
+
+- Use one-time witnesses and `sui::package::Publisher` for package bootstrap authority.
+- Burn or otherwise consume `Publisher` after one-time bootstrap; do not store it as long-lived app state.
+- Use capability objects for ongoing admin or config authority instead of privileged `admin: address` fields.
+- Address fields are acceptable for identity, beneficiary, creator, or payout routing state, but not privileged authorization.
+- Use derived objects with explicit key types when a package needs a deterministic singleton or namespace object.
+- If a singleton root exists, derive related singleton admin/config capabilities from that root with separate key types.