Upload files to "Planning"

Planning/01-corporate-ladder-brainstorm.md

@@ -0,0 +1,231 @@
+# Corporate Ladder Game — Big Picture Brainstorm
+
+This document captures the full vision for the game: everything on the table, from
+the near-term prototype through the long-term dream version. Not everything here
+gets built at once — this is the idea space the architecture needs to be able to
+grow into.
+
+## Core Concept
+
+A browser-based career simulation game. The player starts at the bottom of an
+organization (e.g. the mailroom in a modern corporate setting) and plays through
+turns (a day or a week each), making choices that shape their career, finances,
+relationships, and reputation.
+
+It is **not** a pure narrative experience — there is real scoring, real numeric
+state, and real progress to track. It is also not a spreadsheet optimization
+game — the numbers exist to give the story stakes and a scoreboard, not to reward
+min-maxing. The target feel is **light and fun**, with enough rigor underneath
+that choices matter.
+
+## Gameplay Pillars
+
+### 1. Choose-Your-Own-Adventure + Simulation Hybrid
+
+- Early version: scripted choices. Each turn presents a small, fixed set of
+  options (e.g. 2–3 actions).
+- Later version: free-text player input. The player types what they want to do
+  in their own words, and an AI layer interprets that into a game action (e.g.
+  "I stay late and grind it out" → *hard work* action; "I look for a way to
+  duck out early" → *shortcut* action). The AI can also generate more colorful,
+  varied dialogue and flavor text around the outcome.
+- Underneath both modes, the same numeric engine runs: money, stats,
+  relationships, skills.
+
+### 2. Multidimensional Success
+
+- Title/promotion is one axis of success, not the only one.
+- Other axes: skills learned, relationships built, reputation, personal
+  satisfaction.
+- Strategic depth: a player might deliberately stay at a lower level longer to
+  build skills or relationships before pushing for a promotion, rather than
+  always rushing upward. Rushing every promotion should be able to create real
+  downstream problems (skill gaps, thin relationships) — but this should
+  emerge from the choices available, not from punishing math.
+
+### 3. Skills as Gates, Not Just Flavor
+
+- Skills (e.g. negotiation, technical ability) are tracked stats.
+- Low skill in an area can lock out certain choices entirely, or make them
+  much riskier.
+- Skills grow **organically**, as a side effect of taking related actions and
+  events — not through a dedicated "go train" menu. The goal is to avoid a
+  grindy, click-here-click-there feel. Growth should feel like something that
+  happens to you as a consequence of living the story, not a chore you manage.
+
+### 4. Characters with Real Weight
+
+- Every character has flavor description text (appearance, personality quirks
+  — tall, charismatic, particularly attractive, gruff, etc.) purely for color.
+- Underneath, characters carry real relationship stats toward the player:
+  - How much they **like** you
+  - How much they **fear** you
+  - How much they're willing to **help** you
+- A darker mechanic: leverage/pressure material — not necessarily
+  "blackmail" in the extreme sense, but things a character wouldn't want to
+  come out, which the player can use as a lever to influence behavior. This
+  gives the player a second currency beyond money: information and
+  reputation as power.
+- Influence is central to gameplay — persuading a boss to let you leave
+  early, or a coworker to cover your shift, might work because you've been
+  kind to them (they like you) or because you've been intimidating (they fear
+  you). Different relationship paths should lead to similar outcomes through
+  different means.
+- Characters should have extensive, distinct backstories, so that even when
+  the underlying stat skeleton is the same across playthroughs, individual
+  characters feel different and memorable each time.
+
+### 5. Random Events, Built to Scale
+
+- The initial version should have a small, tightly scoped set of random
+  events.
+- Critically, the underlying data structures for events (and everything else)
+  should be built so that adding new events later is just adding new data —
+  never a rewrite of game logic. Events and choices should be treated as data
+  the engine reads generically, not hardcoded logic scattered through the
+  codebase.
+
+### 6. Soft Failure, Not Game Over
+
+- No hard "you lose" state.
+- Failure is a spiral of **suffering and reduced options**, not a dead end:
+  - Bankruptcy might force taking out a loan.
+  - A demoted or struggling player might have to do menial work for, or take
+    orders from, someone they used to outrank.
+  - The player can always keep pushing to climb back out, at a cost.
+- A player can choose to walk away because it's "too painful," but the game
+  itself doesn't force an ending on them.
+- This keeps players engaged in the story even at rock bottom, and it opens up
+  strong narrative beats — being humbled by a character you were dismissive of
+  earlier should hit differently than being humbled by a stranger.
+
+### 7. Open-Ended Pacing with a Natural Ceiling
+
+- No fixed turn count or forced ending.
+- The game naturally self-limits: once a player becomes, say, company
+  president with influence over everyone, there's nowhere higher to climb —
+  the sandbox is exhausted, not because a clock ran out.
+- The "ending," whenever a player stops, is the same regardless of how far
+  they got: a **career retrospective** — what you did, what you didn't do,
+  key relationships, notable moments (and eventually notable
+  images/videos), presented uniformly whether the player "won" or "lost."
+
+### 8. Single Player Only
+
+- No multiplayer, no competitive syncing across players. This simplifies a
+  large amount of design and technical complexity and keeps the focus on the
+  player's individual story.
+
+### 9. Infinite Themes via Data-Driven Design
+
+This is one of the most important architectural commitments:
+
+- The game engine, mechanics, and code should **never need to change** to
+  support a new setting or theme.
+- Theme is purely a data layer: character archetypes, job titles, event
+  flavor text, tone, and even the *boundaries of allowed content* are all
+  swappable data/content packs.
+- Example themes: modern corporate (primary/default), auto manufacturing,
+  high-tech startup, Wild West, medieval guild, sci-fi/Star Trek-style,
+  textile mill, or even a kid-friendly "lemonade stand" version for younger
+  players.
+- Content packs also control maturity level: a kid-friendly theme keeps
+  everything light, while a more adult theme could unlock sharper-edged
+  mechanics (like real blackmail-style pressure points) — the mechanics
+  underneath stay identical; only the data changes what's permissible and how
+  it's flavored.
+- Replayability also comes from randomized competitive density — e.g. one
+  playthrough might have five rivals competing for the same mailroom
+  promotion, another might have just one. Same mechanics, very different felt
+  experience.
+
+### 10. AI Integration (Long-Term)
+
+- **Dialogue and interpretation**: free-text player input gets interpreted by
+  an AI into structured game actions, and the AI generates more natural,
+  varied dialogue for NPCs and outcomes.
+- **Stateless inference architecture**: this is an important technical
+  decision. The inference engine itself (e.g. a local Llama-class model) is
+  stateless — it's a pure function that takes an assembled prompt and returns
+  a response. It does not maintain any memory or state of its own.
+  - All state — player situation, history, current stats, active theme/genre,
+    scene context — lives at the **application/game engine layer**.
+  - The game engine is responsible for assembling the right context and
+    building the prompt fresh on every call.
+  - This keeps the game portable across different inference backends and
+    keeps behavior predictable and debuggable.
+- **Configurable inference endpoint**: rather than the game hosting or
+  depending on a specific AI service, the configuration should include a
+  pointer to an inference engine (e.g. a local Llama-equivalent server) that
+  the user points at themselves. The core game should never require Jesse to
+  run or pay for a hosted inference service.
+- **Generated media (further out)**: AI-generated images or short video
+  vignettes for big narrative payoff moments — e.g. an award ceremony
+  producing a generated image of the player receiving a medal, or a short
+  video vignette for a major win. This is explicitly a "big picture" /
+  aspirational feature, well downstream of the prototype.
+
+### 11. Logging & Feedback, Built In From Day One
+
+This should exist even before any AI is involved, starting with the very first
+scripted-only prototype:
+
+- **Full instrumentation**: every player action and its resulting effect
+  should be captured/logged from turn one. This serves two purposes:
+  1. Playtesting research — understanding what players actually do and want.
+  2. Future AI tuning — once AI-driven dialogue/interpretation exists, having
+     a baseline of real scripted interactions to compare against.
+- **In-game feedback widget**: a persistent "feedback to game designer"
+  element on the turn screen (can be optionally hidden later once trust in
+  the game is established, but visible by default early on):
+  - Thumbs up / thumbs down / neutral rating per turn.
+  - Optional free-text comment field.
+  - If the player doesn't interact with it, nothing happens — it's fully
+    passive/optional.
+  - This is also the natural place to capture "I wanted to do something that
+    wasn't an available option" feedback, which is gold for identifying where
+    the scripted choice set is too narrow.
+- **Separate export stream**: feedback/logging data is captured as its own
+  independent export, distinct from the game save file. It's meant for
+  Jesse's review and analysis, not for reloading into a playthrough.
+
+## Technical Direction (Big Picture)
+
+- **Browser-based, client-heavy**: strong preference for a simple tech stack
+  that runs entirely client-side (HTML/CSS/JavaScript), with no heavy backend
+  services required. Ideally the only server-side requirement (if any) is
+  serving the static page.
+- **Saves**: browser local storage as the default/primary save mechanism, with
+  an explicit export/import (save-to-file) option so an accidental cache
+  clear or browser crash doesn't destroy a career in progress.
+- **Data schema**: characters and events should carry tags/flags (e.g.
+  department, role type like rival/mentor/peer for characters; stage/level
+  and which stats are affected for events) so the engine can query and filter
+  generically, instead of hardcoding per-entity logic.
+- **Extensibility as a first-class constraint**: every system (events,
+  characters, themes) should be structured as data the engine reads, so that
+  adding new content later doesn't require reworking the engine.
+
+## Relationship to Jesse's Other Project
+
+Jesse is separately building an **interactive story** project that is purely
+narrative-focused, with no game mechanics or scoring layer. This corporate
+ladder game is explicitly the opposite emphasis: it must have real scoring and
+measurable progress, not just storytelling. There may be shared code or
+techniques between the two (especially around AI-driven dialogue/story
+generation), but they are distinct projects with distinct goals.
+
+## Open Questions / Things to Revisit Later
+
+- What's the full list of core character fields beyond name, role/title,
+  relationship stats (like/fear/help), and flavor description? (Tags for
+  department and role-type like rival/mentor/peer were agreed as a good
+  addition.)
+- What's the full list of core event fields beyond description and effects?
+  (Tags for stage/level and affected stats were agreed as a good addition.)
+- How exactly does a player move between tiers/levels once promotion is
+  introduced (post-MVP)?
+- What does the "career retrospective" screen actually look like/contain in
+  detail?
+- How should the feedback widget's visibility toggle work, and when should it
+  default to hidden vs. shown?

Planning/02-corporate-ladder-mvp-spec.md

@@ -0,0 +1,151 @@
+# Corporate Ladder Game — Minimum Viable Prototype (MVP) Spec
+
+This is the scope for the **first playable version**. It intentionally leaves
+out AI, promotion, multiple themes, and generated media — but it must be built
+on data structures that support all of that later without a rewrite.
+
+## Goal of This Version
+
+Prove out the core turn loop: scripted choices → stat/relationship/money
+changes → open-ended replayable play → an ending retrospective whenever the
+player chooses to stop. Validate that the loop is fun in its simplest possible
+form before adding complexity.
+
+## Scope: What's IN
+
+- **Single setting/theme**: modern corporate office, mailroom level only.
+- **Single tier**: no promotion mechanic yet. The player stays in the mailroom
+  and can keep playing indefinitely.
+- **Turns**: each turn represents a day or a week (pick one for the
+  prototype — day is likely simpler to reason about first).
+- **Two characters**:
+  - One boss (authority figure — approves/denies requests, can make life
+    easier or harder).
+  - One coworker rival (peer-level, competing for the same eventual
+    promotion, can help or hinder).
+  - Both have: name, flavor description (personality/appearance color text),
+    and the three relationship stats (likes-you, fears-you, wants-to-help-you)
+    toward the player.
+  - Both have tags for role type (e.g. `boss`, `rival`) so later additions of
+    more characters (mentor, peer, etc.) slot into the same schema.
+- **Player stats**:
+  - Money (with basic income and basic recurring costs).
+  - At least one skill (e.g. negotiation) that can grow organically from
+    relevant choices and can gate at least one choice option.
+  - The three relationship-facing stats as tracked per-character (not global).
+- **Choices per turn**: a small, fixed set (2–3 scripted options), each with
+  a clear immediate effect on stats/relationships/money. No free-text input
+  yet — that's a later phase.
+- **Random events**: a very small number (a handful) of simple scripted
+  events that can occasionally fire instead of, or alongside, a normal turn's
+  choice set. Kept minimal, but implemented through the same generic
+  event-data structure the full game will use later (not a special-cased
+  hack).
+- **Soft failure state**: at least one basic version of the "soft failure"
+  loop — e.g. if money goes negative, the player is offered a demeaning
+  option (take a loan, do a favor for the rival) rather than the game ending.
+- **Open-ended play**: no turn cap. The player can keep taking mailroom turns
+  for as long as they want.
+- **Ending / retrospective**: a simple end-of-session summary screen the
+  player can trigger (e.g. a "wrap up my career" action, or reaching it when
+  they close out), showing: final money, final relationship stats per
+  character, and a short list of notable moments/events that occurred. This
+  screen should look the same in structure whether the player did "well" or
+  "poorly" — it's a summary, not a win/lose screen.
+- **Save system**:
+  - Browser local storage as the live/default save.
+  - Explicit export-to-file and import-from-file so progress survives a
+    cleared cache or browser crash.
+- **Feedback & logging system** (present from turn one, even without AI):
+  - A persistent, always-visible-by-default feedback widget on the turn
+    screen: thumbs up / thumbs down / neutral, plus an optional free-text
+    comment box. No action required — ignoring it does nothing.
+  - Every player action and its resulting effects are logged.
+  - Feedback and logs are captured in their own **separate export**, distinct
+    from the game save file.
+- **Data-driven structure for everything above**: characters, events, and
+  choices should all be represented as data (e.g. JSON-like structures) that
+  a generic engine reads and processes — not hardcoded if/else logic per
+  character or event. This is the seed of the "themes are just data" and
+  "events are just data" architecture from the big-picture vision.
+
+## Scope: What's explicitly OUT (for now)
+
+- No promotion or second tier.
+- No free-text/AI-driven input or dialogue.
+- No AI-generated images or video.
+- No multiple themes/settings (mailroom/corporate only).
+- No multiplayer (never planned — out of scope permanently, not just for
+  MVP).
+- No complex leverage/blackmail system yet — at most a placeholder field on
+  characters that isn't deeply used yet.
+- No account system — local storage + file export/import only.
+- No dedicated "training" or skill-grinding menu — skill growth stays
+  incidental to choices.
+
+## Tech Stack for MVP
+
+- Fully client-side: HTML, CSS, and JavaScript, runnable directly in a
+  browser with no required backend.
+- If any server component exists at all, it should be limited to serving
+  static files — no game logic server-side.
+- No external dependencies beyond what's needed to keep the app simple and
+  self-contained (avoid heavy frameworks unless there's a clear reason).
+- Game state, character data, and event data should be structured as plain
+  data objects/files so they can later be swapped or extended (new themes,
+  more events, more characters) without touching engine code.
+
+## Suggested Data Shape (Starting Point)
+
+This isn't final, but gives a concrete starting schema for the MVP:
+
+**Character**
+- `id`
+- `name`
+- `role_type` (tag, e.g. `boss`, `rival`)
+- `description` (flavor text)
+- `likes_you` (number)
+- `fears_you` (number)
+- `wants_to_help_you` (number)
+
+**Event / Turn Choice**
+- `id`
+- `stage_tag` (e.g. `mailroom`) — for future filtering by level
+- `description` (flavor text shown to player)
+- `options[]`, each with:
+  - `label`
+  - `effects` (changes to money, skill, relationship stats)
+  - `requires` (optional skill/stat gate)
+
+**Player State**
+- `money`
+- `skills` (map of skill name → value)
+- `relationships` (map of character id → stat object)
+- `history` (log of turns taken, for the retrospective screen)
+
+**Feedback Log Entry** (separate export, not part of save)
+- `turn_id`
+- `action_taken`
+- `rating` (up / down / neutral / none)
+- `comment` (optional text)
+- `desired_but_unavailable_action` (optional text, if the player wanted
+  something not offered)
+
+## Definition of Done for MVP
+
+The prototype is "done" when a player can:
+
+1. Start a new game in the mailroom.
+2. Take repeated turns, choosing from a small set of scripted options each
+   time, watching money, skill, and relationship stats change.
+3. Occasionally encounter one of the small set of random events.
+4. Hit a soft-failure scenario (e.g. run out of money) and be offered a
+   demeaning-but-survivable option instead of a game over.
+5. Leave optional feedback (thumbs up/down/neutral + comment) on any turn.
+6. Save and reload their game via local storage, and export/import via file.
+7. Trigger an end-of-session retrospective screen summarizing their run.
+8. Keep playing indefinitely if they choose to, with no forced ending.
+
+All of this should be built on data structures (for characters, events, and
+choices) that will support adding new events, new characters, a promotion
+tier, and eventually new themes — without needing to rewrite the core engine.

Planning/03-claude-code-build-prompt.md

@@ -0,0 +1,171 @@
+# Claude Code Build Prompt — Corporate Ladder Game MVP
+
+Copy everything below the line into Claude Code as your starting prompt.
+
+---
+
+I want to build a browser-based career simulation game called (working title)
+"Corporate Ladder." This is a **minimum viable prototype** — please treat this
+as the first phase of a larger project, and follow a research/plan-first
+approach before writing code: propose a file/folder structure and data schema
+first, surface any open questions, and get my explicit go-ahead before you
+start implementing.
+
+## Core Concept
+
+A turn-based career sim. The player starts in the mailroom of a modern
+corporate office. Each turn (treat a turn as one day), the player is shown a
+short scripted scenario and picks from 2–3 choices. Choices affect the
+player's money, a skill stat, and relationship stats with two NPCs (a boss and
+a coworker rival). The game has no fixed length — the player can keep taking
+turns indefinitely — and at any point can trigger a "wrap up my career"
+retrospective screen summarizing what happened.
+
+This is explicitly a **prototype/foundation**, not the full game. The most
+important requirement is that everything be **data-driven**: characters,
+events, and choices should live in data structures (JSON or equivalent) that
+a generic engine reads and processes. Do not hardcode character-specific or
+event-specific logic in the engine — the engine should not need to change to
+add a new character or event, and eventually should not need to change to
+support an entirely different theme/setting (e.g. Wild West instead of
+corporate office). Please design the schema with that future flexibility in
+mind, even though this build only needs to ship the corporate/mailroom
+content.
+
+## Tech Stack
+
+- Fully client-side: plain HTML, CSS, and JavaScript. No required backend —
+  it should be able to run by opening a static HTML file (or via a trivial
+  static file server for local dev).
+- Keep dependencies minimal. Avoid heavy frameworks unless you think there's
+  a strong reason — I'd rather this stay simple and easy to reason about.
+- No database, no accounts. State lives client-side.
+
+## Required Features for This Build
+
+### 1. Core Turn Loop
+- Player starts a new game in the mailroom with starting values for money,
+  one skill (e.g. "negotiation"), and neutral relationship stats with the two
+  NPCs.
+- Each turn presents a short text scenario and 2–3 choices.
+- Choices apply effects to money / skill / relationship stats.
+- Some choices may require a minimum skill level to be available (a simple
+  gating mechanism).
+- No fixed number of turns — the player can keep playing.
+
+### 2. Two NPCs
+- A boss and a coworker rival.
+- Each has: name, a short flavor description (personality/appearance text,
+  purely for color), a role-type tag (`boss` / `rival`), and three numeric
+  relationship stats toward the player: `likes_you`, `fears_you`,
+  `wants_to_help_you`.
+- Design the character schema so additional role types (e.g. `mentor`,
+  `peer`) could be added later without changing engine code.
+
+### 3. Random Events
+- Implement a small handful (4–6) of simple random events using the *same*
+  data structure as regular scripted turns — i.e. an event is just another
+  entry in the event/turn data with a tag marking it as a random event and
+  some trigger condition (e.g. a probability or a stat threshold). Do not
+  special-case these in the engine logic.
+
+### 4. Soft Failure State
+- If money drops below zero (or some defined threshold), don't end the game.
+  Instead, surface a distinct "hard times" branch of choices — e.g. take out
+  a loan (debt that must be paid down over time) or do a demeaning favor for
+  the rival (which affects relationship stats and possibly unlocks money).
+  The player should be able to work their way back out.
+
+### 5. Retrospective / Ending Screen
+- A "wrap up my career" action the player can take at any time.
+- Shows: final money, final relationship stats with each NPC, and a short
+  list of notable moments/events from their playthrough (pull from a simple
+  history log kept during play).
+- This screen's structure should be the same regardless of how the
+  playthrough went — it's a summary, not a win/lose screen.
+
+### 6. Save System
+- Auto-save to browser local storage as the player progresses.
+- An explicit "Export Save" button that downloads the current game state as a
+  JSON file, and an "Import Save" option to load one back in.
+
+### 7. Feedback & Logging System
+- On every turn screen, include a small, always-visible (for now) feedback
+  widget: thumbs up / thumbs down / neutral buttons, plus an optional
+  free-text comment box. The player is never required to interact with it.
+- Also include an optional field where the player can note "something I
+  wanted to do that wasn't an option here."
+- Log every turn's chosen action and its effects, along with any feedback
+  given, to a **separate log** that is exportable independently from the game
+  save (a separate "Export Feedback Log" button/JSON file). This should not
+  be mixed into the save-game file.
+
+## Data Schema (Starting Point — feel free to refine, but keep me in the
+loop on changes)
+
+```
+Character:
+  id: string
+  name: string
+  role_type: string        // e.g. "boss", "rival"
+  description: string      // flavor text
+  likes_you: number
+  fears_you: number
+  wants_to_help_you: number
+
+TurnEvent:
+  id: string
+  stage_tag: string         // e.g. "mailroom" (for future level filtering)
+  is_random_event: boolean
+  description: string
+  options: [
+    {
+      label: string
+      effects: { money?: number, skills?: { [name]: number },
+                 relationships?: { [character_id]: { likes_you?: number,
+                 fears_you?: number, wants_to_help_you?: number } } }
+      requires?: { skill: string, min: number }
+    }
+  ]
+
+PlayerState:
+  money: number
+  skills: { [name]: number }
+  relationships: { [character_id]: { likes_you, fears_you,
+    wants_to_help_you } }
+  history: [ { turn_id, event_id, choice_label, timestamp } ]
+
+FeedbackLogEntry:
+  turn_id: string
+  action_taken: string
+  rating: "up" | "down" | "neutral" | null
+  comment?: string
+  desired_but_unavailable_action?: string
+```
+
+## What NOT to Build Yet
+
+- No promotion mechanic or second tier/level — mailroom only for this build.
+- No AI/LLM integration of any kind yet — this build is fully scripted.
+- No AI-generated images or video.
+- No multiple themes/settings — corporate/mailroom only, but keep the schema
+  theme-agnostic in spirit (i.e. don't bake "mailroom" assumptions into the
+  engine logic itself, keep it in the data).
+- No multiplayer — this is a permanent design decision, not just an MVP gap.
+- No account system or server-side persistence.
+
+## Process
+
+Please:
+1. Propose a project structure and confirm the data schema with me before
+   writing implementation code.
+2. Flag any open questions (e.g. exact starting stat values, exact effect
+   magnitudes) rather than guessing silently — reasonable defaults are fine
+   but call them out.
+3. Build incrementally, and let's check in after the core turn loop works
+   before layering on the feedback system, save/export, and random events.
+4. Keep commits small and incremental rather than one giant commit at the
+   end.
+
+Let me know once you've reviewed this and have a proposed structure, or if
+you have clarifying questions before we start.