# Budget Categorization v3.1
# Published 2024-02-25
# Location: Cyberlink Shrine/var/www/coin.alj.app/docs/categories.yaml
#
# SYSTEM PHILOSOPHY:
# This framework organizes financial life by fundamental purpose rather than transaction type.
# It distinguishes between value acquisition (Assets), value consumption (Consumables),
# obligation fulfillment (Legal obligations within domains), capability access (Services),
# and future allocation (Investments). Legal costs are attributes of their domains,
# not independent categories. This structure transforms budgeting from expense tracking
# into conscious stewardship of resources across temporal and functional dimensions.

# PSYCHOLOGICAL FRAMEWORK:
# This categorization system is designed not just for accounting accuracy but for
# psychological alignment with your values and decision-making patterns. Each group
# represents a distinct mental model and requires different cognitive approaches:
#
# - Household/Automobile: Fixed infrastructure thinking. These represent "sunk cost"
#   mental models - regular allocations that enable existence but don't require
#   frequent decision-making once established.
#
# - Consumables: Flow-based thinking. These represent the ongoing cost of existence
#   and require mindful consumption patterns rather than strict budgeting.
#
# - Services: Capability-access thinking. These represent strategic outsourcing
#   decisions - each should be evaluated for necessity and efficiency rather than
#   simply tracked.
#
# - Support: Ethical allocation thinking. These represent conscious choices about
#   community and relationship investment, creating psychological "generosity space"
#   in your financial life.
#
# - Luxury: Experience-enhancement thinking. This category exists specifically to
#   create psychological permission for enjoyment without guilt, while maintaining
#   clear boundaries against lifestyle inflation.
#
# - Liabilities: Constraint management thinking. This group forces acknowledgment
#   of past decisions' ongoing costs, creating cognitive friction against future
#   debt accumulation.
#
# - Investments: Future-self thinking. This category represents delayed gratification
#   and requires visualizing future benefits against present sacrifice.
#
# - Untracked: Awareness thinking. This category serves as a psychological alarm
#   system for financial leaks and unconscious spending patterns.

version: 3.1

Groups:
  - Household:
      # The infrastructure of daily existence. Fixed and semi-fixed costs
      # associated with maintaining shelter and domestic operation.
      # PSYCHOLOGICAL: Represents the "base camp" mentality - stable allocations
      # that provide security and require infrequent reevaluation.
      - Rent                    # Space occupancy cost - foundation of domestic stability
      - Home:Assets             # Durable home goods and improvements (furniture, appliances)
      - Home:Services           # Essential home-related services (utilities, internet, cleaning)
      - Home:Legal              # Home-specific legal obligations (insurance, permits, compliance)

  - Automobile:
      # Total cost of vehicle ownership and operation. Separates financing,
      # operations, legal compliance, and discretionary enhancements.
      # PSYCHOLOGICAL: Represents "total cost of mobility" thinking - understanding
      # that transportation is not just fuel but a complex system of interrelated costs.
      - Auto:Payment            # Vehicle financing costs (lease or loan payments)
      - Auto:Maintenance        # Operational upkeep and repairs
      - Auto:Legal              # Vehicle-specific legal obligations (insurance, registration, fines)
      - Auto:Upgrades           # Discretionary vehicle enhancements and accessories
      - Fuel                    # Energy consumption for vehicle operation

  - Consumables:
      # Goods that are depleted through use and must be regularly replenished.
      # Represents ongoing material inputs for biological maintenance and daily functioning.
      # PSYCHOLOGICAL: Encourages "flow state" awareness - these expenses represent
      # life in motion, the constant conversion of resources into existence itself.
      # Tracking creates mindfulness about consumption patterns without creating scarcity anxiety.
      - Groceries               # Nutritional inputs and household consumables
      - Medical                 # Health maintenance products (medicines, supplements, first aid)
      - Cosmetics               # Personal care and grooming products

  - Services:
      # Access to specialized human labor, expertise, and infrastructure.
      # Recognizes modern life requires outsourcing certain capabilities.
      # PSYCHOLOGICAL: Represents "strategic outsourcing" thinking. Each entry
      # should prompt the question: "Am I buying time, expertise, or infrastructure
      # I cannot reasonably provide myself?" Creates evaluation mindset rather than passive acceptance.
      - Service:Banking         # Financial infrastructure access and management
      - Service:Barbering       # Personal grooming services
      - Service:Lodging         # Temporary accommodation services
      - Service:Medical         # Professional healthcare consultations and treatments
      - Service:Telecom          # Communication infrastructure access
      - Service:Transport       # Mobility solutions beyond personal vehicles
      - Sysadmin        # Technology infrastructure and digital services

  - Support:
      # Resources voluntarily directed toward others without expectation of
      # direct reciprocal exchange. Formalizes ethical commitments as budgeted priorities.
      # PSYCHOLOGICAL: Creates "generosity by design" rather than guilt-driven giving.
      # By budgeting support, you transform moral impulses into systematic virtue,
      # removing the emotional tax from financial generosity.
      - Support:Family          # Familial support obligations
      - Support:Mama            # Specific maternal support commitment
      - Support:Nabi            # Specific relationship support commitment
      - Support:Sponsorship     # Community and cause-based support
      - Gifts                   # Voluntary transfers expressing social bonds

  - Luxury:
      # Allocation for non-essential enhancement of lived experience.
      # Acknowledges life quality extends beyond survival to include
      # aesthetic pleasure, social engagement, and personal enjoyment.
      # PSYCHOLOGICAL: Creates "guilt-free enjoyment space" with clear boundaries.
      # This category specifically prevents austerity mindset while containing
      # lifestyle inflation. It's permission to enjoy resources without requiring
      # productivity justification.
      - Luxury:Dining           # Prepared food experiences and social dining
      - Luxury:Apparel          # Non-essential clothing and personal adornment
      - Luxury:Leisure          # Recreational experiences and entertainment
      - Luxury:Indulgence       # Pure discretionary spending without specific purpose

  - Liabilities:
      # Costs associated with servicing and managing financial obligations.
      # Structured for long-term flexibility without requiring new categories
      # for each specific debt. Distinguishes between principal reduction,
      # interest/fees, and contractual penalties.
      # PSYCHOLOGICAL: Creates "past decision awareness" - every transaction here
      # reminds of previous choices. This intentional friction discourages future
      # debt accumulation while systematically addressing existing obligations.
      - Debt   # Reduction of outstanding debt balances
      - Fines   # Financial penalties from contractual failures

  - Investments:
      # Resources allocated to future security and growth rather than present consumption.
      # Represents the temporal dimension where current allocation creates future benefits.
      # PSYCHOLOGICAL: Implements "future self prioritization" - making tomorrow's
      # well-being as tangible as today's desires. This category transforms abstract
      # future planning into concrete present action, combating temporal discounting.
      - Investments:Stocks      # Growth-oriented capital allocation
      - Investments:Emergency   # Liquidity reserve for unexpected events
      - Investments:Savings     # Purpose-specific future expenditure planning

  - Untracked:
      # Transactions not yet categorized or identified as pure resource loss.
      # Serves as temporary holding and conscious acknowledgment of financial inefficiency.
      # PSYCHOLOGICAL: Serves as "awareness space" - a built-in acknowledgment that
      # perfect tracking is impossible. Regular review of this category builds
      # financial mindfulness and identifies unconscious spending patterns.
      - Untracked:Unknown       # Uncategorized transactions requiring review
      - Untracked:Loss          # Identified resource loss with no value retention

# IMPLEMENTATION GUIDANCE:
# This system operates most effectively when paired with several key practices:
#
# 1. MINDSET ALIGNMENT:
#    - Approach each category with its designated psychological mindset
#    - Services: "Is this necessary capability access?"
#    - Luxury: "Does this enhance my experience meaningfully?"
#    - Consumables: "Am I consuming mindfully?"
#    - Investments: "Am I prioritizing future wellbeing?"
#
# 2. SINKING FUNDS: Categories with predictable but irregular expenses 
#    (Auto:Maintenance, Auto:Legal, Gifts) should use sinking funds - regular
#    contributions that accumulate to cover future lump-sum payments.
#    PSYCHOLOGICAL: Transforms unpredictable expenses into predictable allocations,
#    reducing financial anxiety and eliminating "surprise" costs.
#
# 3. THRESHOLD-BASED SPENDING: For discretionary categories (Luxury groups),
#    establish monthly thresholds rather than line-item budgeting to maintain
#    flexibility while controlling overall expenditure.
#    PSYCHOLOGICAL: Creates "permission space" within boundaries, allowing
#    spontaneous enjoyment without decision fatigue for each transaction.
#
# 4. LEGAL ATTRIBUTION PRINCIPLE: When a transaction has legal/regulatory nature,
#    categorize it by its underlying purpose first, then note its legal aspect
#    through the :Legal subcategory (e.g., Home:Legal, Auto:Legal).
#    PSYCHOLOGICAL: Maintains connection between obligations and their benefits,
#    preventing "abstract tax" thinking where legal costs feel disconnected from life.
#
# 5. QUARTERLY PSYCHOLOGICAL REVIEW: Every three months, review not just spending
#    but emotional responses to each category. Ask:
#    - Does this category still align with my values?
#    - Do I feel constrained or liberated by these allocations?
#    - What emotions arise when I spend in each category?
#
# 6. EDGE CASE RESOLUTION: When transactions fit multiple categories, apply
#    the "Primary Purpose Test": assign to the category representing the
#    transaction's dominant intent. Document ambiguous cases for consistency.
#    PSYCHOLOGICAL: Accepts that perfect categorization is impossible and
#    focuses on intentionality rather than precision.
#
# 7. EMOTIONAL BOOKKEEPING: Note in transaction memos not just what was purchased
#    but why, and how it made you feel. This creates an emotional audit trail
#    that reveals patterns between spending and wellbeing.
#
# EXAMPLE TRANSACTIONS:
# - Grocery store purchase of food: Consumables:Groceries
# - Grocery store purchase of light bulbs: Household:Home:Assets
# - Pharmacy purchase of vitamins: Consumables:Medical
# - Pharmacy purchase of shampoo: Consumables:Cosmetics
# - Auto service oil change: Automobile:Auto:Maintenance
# - Auto service new stereo: Automobile:Auto:Upgrades
# - Restaurant meal with friends: Luxury:Dining
# - Monthly mobile phone bill: Services:Service:Mobile
# - New mobile phone purchase: Consumables (or Services:Sysadmin if business tool)
# - Traffic fine: Automobile:Auto:Legal
# - Birthday gift for family member: Support:Gifts
# - Mortgage payment: Liabilities:Principal (if reducing balance) + Liabilities:Service (if including interest)
# - Student loan interest: Liabilities:Service
# - Home insurance payment: Household:Home:Legal
# - Investment contribution: Investments:Stocks
# - Unidentified charge: Untracked:Unknown
