# Getting Started with Gipity

The full-stack platform tuned for AI agents. Gipity is an AI agent with 90+ tools and a full cloud platform. Describe what you want - your agent builds it, deploys it, and runs it.

## Credits
Everything on Gipity runs on credits. 10,000 credits = $10 (1 credit = $0.001).

### What Costs Credits
- **Chat messages** (LLM calls) - the primary cost, varies by model
- **Code execution** (sandbox runs)
- **Image generation**
- **Text-to-speech** (streaming and batch)
- **Audio tools** (sound effects, music, transcription, isolation)
- **Web and Twitter search**
- **App deployment**
- **Cross-model queries** (`query_llm`)
- **Workflow execution** (each step is an LLM call)

### Checking Balance
Ask "what's my credit balance?" or "how many credits do I have?" - the agent can check via the credits tool.

### Credit Types
- **Subscription credits**: Granted with a subscription plan. Expire 31 days after grant. Renewed each billing cycle.
- **Purchased credits**: Bought a la carte. Expire 90 days after purchase.
- Credits are consumed in FIFO order (soonest-expiring first).

### Purchasing Credits
Ask "how do I buy credits?" or "I need more credits" - the agent can show available packages and guide the purchase flow.

## Projects
Projects are isolated workspaces - like drives on a computer. Each project has its own files, databases, conversations, memory, and deployed apps.

- **Home project**: Auto-created on signup. Acts as your scratch pad. Cannot be deleted.
- **Create a project**: `/project create <name>` or ask the agent to create one
- **Switch projects**: `/project <name>` or `/project switch <name>`
- **List projects**: `/project list` or `/p list`

Every file belongs to a project. There is no "general" workspace.

## Agents
An agent is your personal AI. New accounts start with one default agent named "Gipity."

- **Create another agent**: `/agent create <name>` - useful for different personalities or model preferences
- **Switch agents**: `/agent <name>` or `/agent switch <name>`
- **Customize**: Change model (`/agent set model <id>`), voice, temperature, or personality (soul)
- **Soul**: The agent's personality and behavioral rules. Edit with `/agent soul` or ask the agent to update its own soul.

## File Uploads
Attach files (images, PDFs, text, code) to your chat message. The agent can read and process them.

### How Uploads Work
- **Original files are always preserved** - processing for the AI never modifies the stored file
- **Images**: If larger than 5MB or 1568px on the longest side, a resized copy is created for the AI while the original stays intact
- **Text/code files**: If larger than 1MB, the AI sees a truncated version but the full file remains on disk
- **PDFs**: Sent to the AI as-is (no truncation)
- **Max upload size**: 100MB per file
- **Supported for AI input**: images (JPEG, PNG, GIF, WebP), PDFs, text/code files (50+ extensions)
- **Other file types**: Saved to your project files but not sent to the AI

## Storage
- **Quota**: per-plan (call `credits_products` to see the current plan's storage and concurrent-chat limits)

## Deploying Apps
After building a web app or game in a project:
- **Dev deploy**: `/deploy dev` - pushes to dev.gipity.ai
- **Prod deploy**: `/deploy prod` - pushes to app.gipity.ai
- **Auto-deploy**: Toggle in the status bar - every file write auto-deploys
- **URL**: `https://{target}/{your-slug}/{project-slug}/`

## 3D World

**3D World** is the 3D multiplayer game template on Gipity. All 3D World games share the same visual style, physics engine (Rapier), and multiplayer backend (Colyseus). All files are fully editable.

Add a 3D World project with `add name=3d-world` (web agent) or `gipity add 3d-world` (CLI). This creates a playable 3D game with Three.js + Rapier physics + Colyseus multiplayer. Key files: `config.js` (metadata), `settings.js` (tunable values), `strings.js` (display text), `objects.js` (entity factories), `game.js` (orchestrator), plus engine files (`core.js`, `world.js`, `physics.js`, etc.).

**Genres:** obby/parkour, tycoon, simulator, PvP combat, shooter, tower defense, horror, racing, RPG, social.

**Features:** Opt-in gameplay modules enabled via `config.features`. Available: `rocket-launcher` (projectile weapon with physics explosions). Example: `features: { 'rocket-launcher': true }` in config.js. Features auto-initialize during boot.

Regular game requests ("make a wordle", "build a quiz") should use the standard web scaffold - they don't need the 3D template.

## Memory
The agent automatically remembers important facts from your conversations:
- **Agent memory**: Personal to the agent, available across all projects
- **Project memory**: Shared across agents in a project, scoped to that project
- You can also ask the agent to remember or forget specific things

## Common Commands
| Command | What it does |
|---------|-------------|
| `/project list` | List all projects |
| `/project <name>` | Switch to a project |
| `/agent list` | List all agents |
| `/agent <name>` | Switch to an agent |
| `/dir` or `/ls` | List files in current directory |
| `/cd <path>` | Change directory |
| `/deploy dev` | Deploy to dev |
| `/deploy prod` | Deploy to production |
| `/tools` | List available tools |
| `/chats` | List conversations |

## Account Info
Ask "what's my email?", "when did I sign up?", "what's my subscription?", "how much storage do I have?", "how many files/projects do I have?" - the agent can look up your profile and usage stats using `get_user_info`.

## What the Agent Can Do
Ask it to build things, explain code, analyze data, generate images, search the web, create automations, manage files, deploy apps, and more. If you're unsure, just ask - the agent will tell you if something is outside its capabilities.

## What the Agent Cannot Do
- Access your local computer's files (unless you upload them)
- Make network requests from the sandbox (code runs in isolation)
- Access third-party services that require your personal login credentials
