Initial commit: pokebuddy_cli

docs/ART_DIRECTION.md

@@ -0,0 +1,58 @@
+# Art Direction
+
+PokeBuddy uses a cyber-retro terminal style: neon, pixel, ANSI-inspired, dark UI and expressive companions.
+
+## Keywords
+
+- terminal native
+- pixel art
+- ANSI-inspired
+- cyber-retro
+- neon green
+- local-first
+- collectible companions
+- developer tool culture
+
+## Palette
+
+| Token | Hex |
+|---|---|
+| Accent Green | `#00FF90` |
+| Cyan | `#00E6FF` |
+| Yellow | `#FFD60A` |
+| Magenta | `#FF4DFF` |
+| Orange | `#FF6A3D` |
+| Purple | `#A78BFA` |
+| Gray | `#A1A1AA` |
+| White | `#FFFFFF` |
+| Base | `#0B0F14` |
+| Surface | `#11161C` |
+
+## Typography
+
+Recommended:
+
+- Headings: Space Grotesk
+- Terminal/code: JetBrains Mono
+
+For pure terminal output, rely on the user’s configured monospace font.
+
+## Logo
+
+Use the terminal prompt mark as the core logo:
+
+```text
+>_
+```
+
+Keep it simple, kinetic and legible.
+
+## Companion art
+
+Recommended workflow:
+
+1. Sketch as pixel art.
+2. Convert to ANSI/block style where needed.
+3. Keep a compact terminal version.
+4. Keep a high-detail README/brand version.
+5. Never use official third-party sprites or derivatives.

docs/BRAND.md

@@ -0,0 +1,29 @@
+# Brand System
+
+PokeBuddy CLI is a playful developer tool with a serious product spine.
+
+## Core message
+
+> Tiny terminal companions you can poke while you code.
+
+## Expanded message
+
+PokeBuddy CLI brings living terminal companions to your workflow. They react to your commands, remember your progress and make development feel more alive.
+
+## Voice
+
+- playful, but not childish;
+- technical, but not dry;
+- warm, but not noisy;
+- memorable, but not legally reckless.
+
+## Taglines
+
+- Tiny terminal companions you can poke while you code.
+- POKE. CODE. REPEAT.
+- Your code. Their company. Endless possibilities.
+- Tiny friends. Big commits.
+
+## Boilerplate
+
+PokeBuddy CLI is an open-source, local-first terminal companion system for developers. Hatch collectible companions, interact with them from your shell and let them react to your coding workflow.

docs/COMMANDS.md

@@ -0,0 +1,67 @@
+# Commands
+
+## `pokebuddy hatch`
+
+Hatches a companion and stores it locally.
+
+```bash
+pokebuddy hatch
+pokebuddy hatch --force
+pokebuddy hatch --all
+```
+
+## `pokebuddy list`
+
+Lists discovered companions.
+
+```bash
+pokebuddy list
+```
+
+## `pokebuddy dex`
+
+Shows every known launch companion.
+
+```bash
+pokebuddy dex
+```
+
+## `pokebuddy show [name]`
+
+Shows a detailed companion card.
+
+```bash
+pokebuddy show zapbit
+```
+
+## `pokebuddy poke [name]`
+
+Interacts with a companion and increases XP.
+
+```bash
+pokebuddy poke zapbit
+```
+
+## `pokebuddy feed [name] [thing]`
+
+Feeds context, cache, file paths or playful offerings.
+
+```bash
+pokebuddy feed cachegoblin ./build/cache
+```
+
+## `pokebuddy status`
+
+Shows local companion state.
+
+```bash
+pokebuddy status
+```
+
+## `pokebuddy rename <name> <alias>`
+
+Gives a discovered companion a local alias.
+
+```bash
+pokebuddy rename zapbit Sparkinho
+```

docs/CREATURE_GUIDELINES.md

@@ -0,0 +1,69 @@
+# Creature Guidelines
+
+PokeBuddy companions should feel original, developer-native and terminal-friendly.
+
+## Design principles
+
+A good companion is:
+
+- memorable at small size;
+- readable in terminal output;
+- strongly associated with a dev concept;
+- cute enough to like;
+- weird enough to remember;
+- original enough to publish safely.
+
+## Companion anatomy
+
+Each companion should define:
+
+- `id`
+- `name`
+- `type`
+- `rarity`
+- `personality`
+- `flavor`
+- `quote`
+- `likes`
+- `dislikes`
+- `stats`
+- `reactions`
+- `ascii`
+
+## Types
+
+Recommended types:
+
+- Logic
+- Spark
+- Storage
+- Memory
+- Void
+- Debug
+- AI
+- Prompt
+- Cache
+- Chaos
+- Git
+- Fire
+- Infra
+- Shell
+- Network
+- Data
+- Security
+- Build
+- Test
+- Docs
+
+## Rarities
+
+- Uncommon
+- Rare
+- Epic
+- Mythic
+
+## Avoid
+
+Do not create companions that copy or closely resemble protected characters, recognizable franchise silhouettes, official sprites, official names or modified official names.
+
+Keep it original. Keep it dev-flavored.

docs/NAMING_GUIDELINES.md

@@ -0,0 +1,48 @@
+# Naming Guidelines
+
+Companion names should be short, original and developer-flavored.
+
+## Good patterns
+
+Blend a technical concept with a creature, object or vibe:
+
+- `Zap` + `bit` → Zapbit
+- `Diskette` + `x` → Diskettex
+- `Null` + `Wisp` → NullWisp
+- `Prompt` + `Moth` → PromptMoth
+- `Cache` + `Goblin` → CacheGoblin
+- `Merge` + `Drake` → MergeDrake
+
+## Good names
+
+- LintFox
+- CronCrab
+- TokenBat
+- EnvImp
+- JsonGecko
+- ApiOtter
+- DockerMole
+- Shellfin
+- ForkSprite
+- BugSlug
+
+## Avoid
+
+Avoid names that are:
+
+- direct references to third-party characters;
+- modified versions of third-party character names;
+- too close to protected brands;
+- hard to pronounce;
+- too generic.
+
+## Test
+
+Ask:
+
+1. Is this name searchable?
+2. Does it evoke a dev concept?
+3. Would it still work without any outside reference?
+4. Could a contributor draw it without copying anything?
+
+If yes, it probably belongs here.

docs/PLUGIN_API.md

@@ -0,0 +1,34 @@
+# Plugin API Draft
+
+The plugin API is planned for a future release. This document is a draft.
+
+## Goals
+
+Plugins should be able to:
+
+- listen to PokeBuddy events;
+- add reactions;
+- add custom commands;
+- create companion packs;
+- integrate with Git hooks, CI, editors and terminals.
+
+## Draft shape
+
+```js
+export default {
+  name: 'my-plugin',
+  version: '0.1.0',
+  onEvent(event, context) {
+    if (event.type === 'commit') {
+      return context.say('Nice commit. Tiny goblin approved.');
+    }
+  }
+};
+```
+
+## Safety rules
+
+- Plugins must be explicit.
+- No hidden network calls.
+- No arbitrary shell execution by default.
+- Plugin permissions should be visible to users.