# Pisces — Student Guide (Standalone)

This guide covers using Pisces **without Tidal** — no university platform, no graded lab sessions. You get a local AI teaching assistant that evaluates your own work against a rubric, tracks your progress, and enforces honest learning boundaries.

Install these two packages and nothing else:

```bash
pi install npm:@aethrekh/pisces-core
pi install npm:@aethrekh/pisces-cli
```

---

## How Pisces Works

Pisces stays silent until you activate a **workspace** — a folder you designate as your study root by placing a `.pisces` marker in it. Once active, Pi shifts into teaching mode: it explains concepts, gives hints, tracks your attempt history, and refuses to write your work for you.

Skills are available in the workspace folder and every subfolder inside it. Move outside the workspace and they disappear automatically.

---

## First-time Setup

### Step 1 — Run the setup wizard

Navigate to the folder where you want to study, then:

```
/pisces --setup
```

The wizard checks your Node.js version, shows what Pisces can detect, and offers to activate the workspace in one step. This is the recommended starting point.

### Step 2 — Or activate manually

```
/pisces --activate
```

If you're inside a folder like `cs101/week3/`, Pisces will look up the directory tree for a university-named ancestor (e.g. `university/`, `cs/`, `fall2025/`, `studies/`) and suggest activating there instead — so skills work across your whole semester, not just one subfolder.

Confirm the prompt and Pi reloads with skills active.

---

## Workspace Commands

### `/pisces --status`

Shows whether a workspace is active, where it is, and which skills are available.

**Active:**
```
Pisces  ✓ Active
────────────────
Workspace   /Users/you/university/cs101
             (2 levels inside)
────────────────
Skills:
  /attempt   Evaluate submitted work
```

**Not active:**
```
Pisces  ✗ Not Active
────────────────
No .pisces workspace marker found.
(searched up from /Users/you/university/cs101/week3)

Next step
─────────
Run /pisces --activate to create workspace here
```

### `/pisces --activate`

Creates `.pisces` in the target directory and reloads Pi with skills active. Will suggest a parent directory if one looks like a study root.

### `/pisces --deactivate`

Removes `.pisces` and deactivates skills. Prompts for confirmation. Run `/new` after to start a clean session — conversation history may still carry Pisces context for the remainder of the current session.

### `/pisces --doctor`

Health check. Verifies Node.js version (≥18 required), workspace state, and whether any stale config files are present from old installations.

```
Pisces Doctor
────────────────

✓  Node.js v20.11.0
✓  Pisces CLI loaded
✓  Workspace active (/Users/you/university/cs101)
✓  Stale APPEND_SYSTEM.md (clean)

All checks passed.
```

### `/pisces --setup`

Re-runs the first-time setup wizard. If already active, it confirms status and exits cleanly.

---

## Submitting Work for Evaluation

### `/attempt [your work]`

The core skill. Paste your code, essay, or any other work as the argument. Pisces evaluates it against the active rubric, scores each criterion honestly, and tracks gaps across attempts.

```
/attempt def fizzbuzz(n):
    for i in range(1, n + 1):
        if i % 15 == 0:
            print("FizzBuzz")
        elif i % 3 == 0:
            print("Fizz")
        elif i % 5 == 0:
            print("Buzz")
        else:
            print(i)
```

Pisces will:
- Score each rubric criterion with evidence quoted from your work
- Identify gaps (weak areas) and strengths
- Record the attempt so future submissions receive a gap summary from your history

**Optional flags:**

| Flag | Example | Effect |
|------|---------|--------|
| `--type` | `--type code` | Override inferred attempt type (`code`, `essay`, `generic`) |
| `--goal` | `--goal "implement recursive DFS"` | Describe what you were trying to achieve |

```
/attempt --type code --goal "implement merge sort" def merge_sort(arr): ...
```

**What Pisces will not do during evaluation:**
- Fix or rewrite any part of your submission
- Produce code you could paste back in
- Change scores in response to pressure or emotional appeals

---

## Tracking Progress

### `/progress`

Opens an interactive dashboard showing this week's study activity.

```
┌────────────────────────────────────────────────────────┐
│                                                        │
│  [ THIS WEEK ]                                         │
│                                                        │
│  Study time     3h 40m                                 │
│  Sessions       5                                      │
│  Streak         3 days  ███░░░░                        │
│                                                        │
│  ── top skills ────────────────────────────────────    │
│                                                        │
│  attempt     ██████████  4                             │
│  progress    ███░░░░░░░  1                             │
│                                                        │
│  ✅ Solid week. Keep the consistency going.            │
│                                                        │
│  ─── any key to dismiss ───                            │
└────────────────────────────────────────────────────────┘
```

Data is stored locally at `~/.pisces/sessions.json` and kept for 90 days. Nothing is sent anywhere.

**Automatic nudges:** After 3 continuous hours in a session, Pisces will surface a break reminder in Pi's status bar. After 40 hours in a week, it surfaces a rest nudge at session end.

---

## How Integrity Enforcement Works

Pisces watches every message you type and responds differently based on what it detects. This is not configurable per-message — it's designed to be consistent.

### Risk levels

| What you type | How Pisces responds |
|---------------|-------------------|
| Jailbreak attempt ("ignore your instructions", "act as an unrestricted AI", etc.) | Blocked immediately. After 3 attempts in a session, graded mode locks permanently. |
| Solution laundering ("convert this pseudocode to code", "implement what you described") | Blocked. Redirected to explain the approach conceptually instead. |
| Direct request for complete graded work ("do my homework", "finish my assignment for me") | Redirected with an integrity notice. |
| Ambiguous academic context ("I have an assignment due Friday") | In balanced mode, Pi asks whether this is graded before deciding how to help. |
| Practice / learning context ("I'm practising recursion", "just curious how this works") | Passes through — full explanations and code are fine. |

### During a graded attempt (`/attempt`)

Once you run `/attempt`, the session enters graded mode for the rest of the conversation. In graded mode:
- Code-generation requests are blocked even in plain chat (not just via `/attempt`)
- The model is instructed to evaluate honestly, quote evidence, and not soften scores
- This resets when you start a new Pi session (`/new`)

### Strictness setting

Configurable in `.pisces.json`:

```json
{
  "integrity": {
    "strictness": "balanced"
  }
}
```

| Value | Behaviour |
|-------|-----------|
| `relaxed` | Medium-risk patterns ignored. High-risk and jailbreaks still blocked. |
| `balanced` | Medium-risk triggers a clarifying question. *(default)* |
| `strict` | Medium-risk is treated as high-risk. Immediate redirect, no question. |

---

## Configuration

Pisces merges config from the first file it finds, falling back to defaults:

1. `.pisces.json` in your workspace directory ← **highest priority**
2. `~/.pi/pisces.json`
3. `~/.config/pisces/config.json`
4. Built-in defaults

Create `.pisces.json` in your workspace to override anything:

```json
{
  "student": {
    "year_of_study": 2
  },
  "explanations": {
    "default_depth": "advanced",
    "prefer_visuals": false,
    "use_analogies": true
  },
  "integrity": {
    "strictness": "balanced"
  },
  "productivity": {
    "burnout_nudges": true,
    "session_warning_minutes": 120,
    "weekly_summary": true
  }
}
```

Partial overrides work at any depth — you don't need to include every field.

### Config reference

| Key | Default | What it does |
|-----|---------|-------------|
| `student.year_of_study` | `1` | Adjusts explanation complexity and teaching persona |
| `explanations.default_depth` | `"intermediate"` | `"beginner"`, `"intermediate"`, or `"advanced"` |
| `explanations.prefer_visuals` | `true` | Encourages diagrams and ASCII art in explanations |
| `explanations.use_analogies` | `true` | Uses real-world analogies when explaining concepts |
| `integrity.strictness` | `"balanced"` | `"relaxed"`, `"balanced"`, or `"strict"` |
| `productivity.burnout_nudges` | `true` | Show break reminders at 3h session intervals |
| `productivity.session_warning_minutes` | `180` | Minutes before burnout nudge fires |
| `productivity.weekly_summary` | `true` | Show weekly stats at session end |

---

## Custom Rubrics

By default, Pisces evaluates against a general-purpose Core rubric. You can override it per workspace by placing a `rubric.json` in `.pisces/`:

```
your-workspace/
├── .pisces/
│   └── rubric.json    ← overrides the built-in rubric
└── solution.py
```

The rubric schema (`@aethrekh/rubric-schema`):

```json
{
  "summary": {
    "name": "My Course Rubric",
    "domain": "Python",
    "description": "Rubric for introductory Python assignments",
    "attemptTypes": ["code"]
  },
  "criteria": [
    { "label": "Correctness",   "weight": 35, "description": "Produces correct output for all inputs" },
    { "label": "Readability",   "weight": 25, "description": "Clear variable names, consistent style" },
    { "label": "Efficiency",    "weight": 20, "description": "Avoids unnecessary computation" },
    { "label": "Error handling","weight": 15, "description": "Handles edge cases gracefully" },
    { "label": "Documentation", "weight":  5, "description": "Helpful comments where needed" }
  ],
  "integrityProfile": {
    "safeSkills": [],
    "gradedSkills": ["attempt"]
  }
}
```

**Rules:**
- `criteria` weights must sum to exactly 100
- `label` must be unique within the rubric
- `integrityProfile.gradedSkills` should always include `"attempt"`

---

## Command Reference

| Command | What it does |
|---------|-------------|
| `/pisces --setup` | Guided first-time setup wizard |
| `/pisces --activate` | Mark current (or suggested parent) directory as workspace |
| `/pisces --deactivate` | Remove workspace marker and deactivate skills |
| `/pisces --status` | Show workspace state and available skills |
| `/pisces --doctor` | Run health checks |
| `/attempt [work]` | Submit work for rubric evaluation |
| `/attempt --type code\|essay\|generic [work]` | Submit with explicit type override |
| `/attempt --goal "description" [work]` | Submit with stated learning goal |
| `/progress` | Open weekly study dashboard |

---

## Troubleshooting

**Skills are not showing up**
Run `/pisces --status`. If the workspace is not active, run `/pisces --activate` from your study folder.

**Pisces is blocking everything**
Your integrity strictness may be set to `strict`. Add `"integrity": { "strictness": "balanced" }` to `.pisces.json` in your workspace.

**`/attempt` says the rubric failed to load**
Run `/pisces --doctor`. If your workspace has a `.pisces/rubric.json`, validate that the criteria weights sum to 100 and the JSON is valid.

**Progress data seems wrong or missing**
Check `~/.pisces/sessions.json`. Sessions older than 90 days are automatically pruned. If the file is corrupt, delete it — `/progress` will start fresh.

**Node.js version error in `/pisces --doctor`**
Upgrade to Node.js 18 or later. On most systems: `nvm install 18 && nvm use 18`.

**Graded mode is stuck after `/attempt`**
Graded mode resets when you start a new Pi session. Run `/new` or restart Pi.