Add public showcase repository structure for Monbii

.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: Lint Markdown
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  markdownlint:
+    name: Markdown lint
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install markdownlint-cli
+        run: npm install -g markdownlint-cli
+
+      - name: Lint markdown files
+        run: markdownlint '**/*.md' --ignore node_modules

LICENSE

@@ -0,0 +1,9 @@
+Copyright (c) 2024 Monbii. All Rights Reserved.
+
+This software and all associated files, documentation, and assets are the
+exclusive property of the copyright holder. No part of this repository may be
+reproduced, distributed, modified, or used in any form without explicit written
+permission from the copyright holder.
+
+Unauthorized use, copying, or distribution of this software, in whole or in
+part, is strictly prohibited.

README.md

@@ -1 +1,76 @@
-# Monbii
+# Monbii 🌱
+
+**A minimalist habit app where your companion grows with your consistency.**
+
+> Source code is private. This repository is a public showcase of the product, its design, and technical thinking.
+
+---
+
+## Live Demo
+
+[**monbii.vercel.app →**](https://monbii.vercel.app/)
+
+---
+
+## Preview
+
+| Home | Habits | Companion | Battle |
+|------|--------|-----------|--------|
+| ![Home](screenshots/home.png) | ![Habits](screenshots/habits.png) | ![Companion](screenshots/companion.png) | ![Battle](screenshots/battle.png) |
+
+> Screenshots coming soon. See [`screenshots/`](./screenshots/) for details.
+
+---
+
+## What is Monbii?
+
+Most habit apps treat consistency as a number. Monbii treats it as a relationship.
+
+Your companion reacts to what you do — or don't do. Complete your habits and it grows. Miss them and it shows. The goal is to make habits feel alive instead of mechanical.
+
+**Core loop:**
+
+- You set habits that matter to you
+- Your companion's state reflects your consistency
+- Streaks drive evolution; neglect triggers visible reactions
+- A battle system adds a layer of engagement tied to your real-world progress
+
+---
+
+## Features
+
+- **Companion system** — A character that evolves with your habit streak
+- **Habit tracking** — Clean, low-friction daily check-ins
+- **Progression & evolution** — Companion grows through defined stages
+- **Battle system** — Companion strength is tied to your consistency
+- **Notifications** — Gentle reminders that feel contextual, not nagging
+
+See [`docs/features.md`](./docs/features.md) for a full breakdown.
+
+---
+
+## Tech Stack
+
+| Layer | Technology |
+|---|---|
+| Frontend | React + Capacitor |
+| State management | Zustand |
+| Backend / cloud | Supabase / Lovable Cloud |
+| Animations | Lottie |
+
+High-level architecture is documented in [`docs/architecture.md`](./docs/architecture.md).
+
+---
+
+## Documentation
+
+- [`docs/overview.md`](./docs/overview.md) — Problem, purpose, and behavioral design
+- [`docs/architecture.md`](./docs/architecture.md) — System architecture (high-level)
+- [`docs/features.md`](./docs/features.md) — Feature breakdown
+- [`docs/roadmap.md`](./docs/roadmap.md) — Upcoming improvements
+
+---
+
+## License
+
+All Rights Reserved. See [`LICENSE`](./LICENSE).

docs/architecture.md

@@ -0,0 +1,59 @@
+# Architecture
+
+This document describes the high-level system architecture of Monbii. Implementation details are not disclosed.
+
+---
+
+## Frontend
+
+**React + Capacitor**
+
+The UI is built with React and compiled to native mobile targets via Capacitor. This allows a single codebase to run on iOS and Android while maintaining access to native device APIs (notifications, haptics, storage).
+
+The component structure is kept flat and feature-scoped. Screens map directly to user-facing concepts: habits, companion, battle.
+
+---
+
+## State Management
+
+**Zustand**
+
+Application state is managed with Zustand. Stores are kept narrow and purpose-specific — one for habits, one for companion state, one for user session. There is no shared global state beyond what's explicitly necessary.
+
+State is persisted locally and synced with the backend on session load and key user actions.
+
+---
+
+## Backend / Cloud
+
+**Supabase / Lovable Cloud**
+
+Monbii uses Supabase for authentication, database, and real-time sync. User habit data, companion state, and progression records are stored server-side and associated with the authenticated user.
+
+Lovable Cloud handles certain deployment and integration layers.
+
+The backend is not exposed publicly. All client-server communication goes through authenticated API calls.
+
+---
+
+## Animation System
+
+**Lottie**
+
+Companion animations and UI transitions use Lottie. Animation files are pre-rendered and triggered by state changes in the companion system. This keeps animations performant and decoupled from rendering logic.
+
+---
+
+## Summary
+
+```
+User Device (iOS / Android)
+        │
+        ▼
+React + Capacitor (Frontend)
+        │
+   Zustand (State)
+        │
+        ▼
+Supabase / Lovable Cloud (Auth, DB, Sync)
+```

docs/features.md

@@ -0,0 +1,39 @@
+# Features
+
+## Companion System
+
+Each user has a companion that exists independently of any individual habit. The companion's visual state — its appearance, animations, and energy level — is a direct reflection of the user's overall consistency.
+
+When habits are completed, the companion responds positively. When habits are missed, its state degrades visibly. This is not binary; the companion occupies a spectrum of states that shift gradually based on behavior over time.
+
+---
+
+## Habit Tracking Loop
+
+Habits are simple, named daily commitments. The check-in interface is intentionally minimal — the user sees their habits for the day and marks them complete. No timers, no detailed logging unless the user wants it.
+
+Each completed habit contributes to the companion's daily score. The system calculates consistency across a rolling window, not just the current day, so one missed day doesn't erase progress.
+
+---
+
+## Progression and Evolution
+
+The companion evolves through distinct stages tied to long-term consistency. Early stages are accessible quickly; later evolutions require sustained effort over weeks or months.
+
+Regression is possible. Prolonged neglect moves the companion backward through stages. This makes the system honest: past progress doesn't protect you indefinitely.
+
+---
+
+## Battle System
+
+The companion's strength in battles is directly tied to habit consistency. Users can engage in battles — the mechanics of which reflect the companion's current state.
+
+This feature is designed to add engagement without distracting from the core habit loop. Battles are a consequence of your habits, not a replacement for them.
+
+---
+
+## Notifications
+
+Notifications are tied to the user's habit schedule and companion state. Reminders are contextual — they reference the companion rather than generic prompts. The companion "reaching out" is more engaging than a standard push notification.
+
+Notification frequency and timing are configurable. The system avoids sending notifications that have no contextual basis.

docs/overview.md

@@ -0,0 +1,27 @@
+# Overview
+
+## The Problem with Traditional Habit Apps
+
+Most habit trackers reduce behavior change to a checklist. You mark tasks complete, see a streak counter increment, and that's the extent of the feedback loop. There's nothing at stake — and nothing that makes you feel the consequence of missing a day beyond a broken number.
+
+This creates a fundamental disconnect: the app treats consistency as data, but humans respond to meaning.
+
+## Why Monbii Exists
+
+Monbii is built around one observation: people form stronger habits when something they care about is affected by their behavior.
+
+A companion that visibly reacts to your consistency creates a relationship. When you check in, your companion grows. When you skip, it shows — not through guilt, but through a living system that reflects your effort.
+
+The goal isn't to shame you into habits. It's to give your consistency a form you can see.
+
+## Behavioral Design Thinking
+
+Monbii draws on a few principles:
+
+**Variable reward without randomness.** Your companion's state changes based on real input — your habits — not chance. Progress feels earned.
+
+**Low-friction check-ins.** The habit tracking interface is intentionally minimal. The moment of check-in should take seconds, not interrupt the day.
+
+**Emotional anchoring.** Attaching behavior to something you care about (your companion) increases recall and follow-through compared to abstract streaks.
+
+**Visible consequence, not punishment.** Missed habits have a visual effect on your companion. This isn't punitive — it's honest. The system reflects what you've put in.

docs/roadmap.md

@@ -0,0 +1,45 @@
+# Roadmap
+
+This document outlines planned improvements and ideas being evaluated for future versions of Monbii.
+
+---
+
+## Near-term
+
+**Onboarding refinement**
+The first-run experience needs to communicate the companion concept quickly. Current onboarding is functional but not emotionally engaging. A short interactive sequence is planned.
+
+**Habit scheduling**
+Currently habits reset daily at midnight. Upcoming: support for habits tied to specific days of the week rather than every day.
+
+**Companion mood persistence**
+The companion's current mood resets at session load. Planned change: mood persists between sessions and changes gradually rather than snapping to a new state on open.
+
+**Offline support**
+Habit check-ins should work without an internet connection and sync on next available connection. Partial offline support exists; full implementation is in progress.
+
+---
+
+## Medium-term
+
+**Multiple companions**
+Users will be able to unlock additional companions through sustained consistency. Each companion has a distinct visual identity and evolution path.
+
+**Social layer (opt-in)**
+An optional feature to share companion state or streak milestones with friends. No leaderboards — sharing is personal, not competitive.
+
+**Habit templates**
+Curated sets of habits for common goals (sleep, fitness, focus) that users can adopt with one tap rather than building from scratch.
+
+---
+
+## Longer-term
+
+**Adaptive difficulty in battles**
+Battle mechanics that scale based on the user's habit history, making the system more challenging as consistency improves.
+
+**Companion memory**
+Companions that reference past behavior in a contextual way — acknowledging long streaks, responding to a return after a gap — to deepen the sense of relationship over time.
+
+**Platform expansion**
+Wider device support and potential web companion experience for users who prefer desktop.

public-demo/link.md

@@ -0,0 +1,16 @@
+# Live Demo
+
+**URL:** [https://monbii.vercel.app/](https://monbii.vercel.app/)
+
+## What you can try
+
+The demo gives access to the core habit tracking and companion experience:
+
+- Create and track daily habits
+- Watch your companion respond to your check-ins
+- Explore the companion evolution system
+- Try the battle screen (companion strength reflects your consistency)
+
+The demo runs on live infrastructure. Creating an account gives you a persistent companion tied to your habit history.
+
+No source code is exposed through the demo environment.

screenshots/README.md

@@ -0,0 +1,16 @@
+# Screenshots
+
+This directory holds product screenshots for use in the README and documentation.
+
+## Planned screenshots
+
+| File | Screen |
+|------|--------|
+| `home.png` | Home screen — companion state and daily summary |
+| `habits.png` | Habit tracking screen — daily check-in view |
+| `companion.png` | Companion detail screen — evolution state and stats |
+| `battle.png` | Battle screen — companion in action |
+
+Screenshots will be added as the product reaches a stable visual state.
+
+To contribute or request updated screenshots, contact the maintainer directly.