ArchiTools/SESSION-GUIDE.md

# ArchiTools — Session Guide for AI Assistants

> How to start, resume, and hand off coding sessions. Keep this file updated.

---

## Starting a Brand New Session

Copy-paste this prompt to any AI coding assistant (Claude Code, Cursor, Windsurf, Copilot, etc.):

```
I'm working on ArchiTools, an internal web dashboard for an architecture office.

Read these files first (in this order):
1. CLAUDE.md — full project context, stack, architecture, conventions
2. ROADMAP.md — complete task list with phases, dependencies, model recommendations
3. SESSION-GUIDE.md — this file, session workflow

The repo is at: http://10.10.10.166:3002/gitadmin/ArchiTools (branch: main)

Start by pulling the latest code, then pick the next uncompleted task from ROADMAP.md
(tasks are ordered by priority — work top to bottom).

Rules:
- Run `npx next build` before every commit (zero errors required)
- Push to main when done (Portainer auto-deploys)
- Update ROADMAP.md: mark completed tasks with ✅ and date
- Update SESSION-LOG.md with what you did
- Notify me when a module/task is ready for my review
- Do NOT move to the next task until I approve the current one
- Code in English, UI in Romanian
```

---

## Resuming Where You Left Off

Copy-paste this prompt when continuing from a previous session:

```
I'm continuing work on ArchiTools.

Read these files first:
1. CLAUDE.md — project context
2. ROADMAP.md — find the next uncompleted task (no ✅)
3. SESSION-LOG.md — see what was done in previous sessions

Pull latest from main first: git pull origin main

Then continue with the next task from ROADMAP.md.

Same rules: build must pass, push when done, update ROADMAP.md and SESSION-LOG.md,
notify me when ready for review.
```

---

## Git Workflow (Pull / Push from Gitea)

### First time setup (clone)
```bash
git clone http://10.10.10.166:3002/gitadmin/ArchiTools.git
cd ArchiTools
npm install
npm run dev
```

### Every session start (pull latest)
```bash
git pull origin main
npm install          # in case dependencies changed
npm run dev
```

### After completing work (push)
```bash
npx next build                    # MUST pass with zero errors
git add <changed-files>           # never git add -A (avoid secrets)
git commit -m "feat(module): description

Co-Authored-By: <model-name>"
git push origin main              # triggers Portainer auto-deploy
```

### If working from a different machine
```bash
git clone http://10.10.10.166:3002/gitadmin/ArchiTools.git
cd ArchiTools
npm install
# read CLAUDE.md, ROADMAP.md, SESSION-LOG.md
# continue working
```

---

## Files to Keep Updated

### After EVERY session, update these files:

#### 1. `ROADMAP.md` — Mark completed tasks

When a task is done and approved by the user, add ✅ and the date:

```markdown
### 1.01 ✅ (2026-02-18) `[LIGHT]` Verify Email Signature Logo Files
```

This is how the next session knows where to pick up.

#### 2. `SESSION-LOG.md` — Append a session entry

Add a new entry at the TOP of the file (newest first):

```markdown
## Session — 2026-02-18 (Opus 4.6)

### Completed
- 1.01: Verified logo files, created placeholders for US/SDT
- 1.02: Added address toggle for Urban Switch

### In Progress
- 1.03: Prompt Generator templates — 4 of 10 done, paused for user feedback

### Blockers
- Need US/SDT logo files from user (task 1.01)

### Notes
- Discovered that `signature-configurator.tsx` has a z-index issue on the color picker
- Build passes, pushed commit abc1234

---
```

#### 3. `CLAUDE.md` — Update if architecture changes

Only update when:
- A new module is added (add to the module table)
- A core system changes (storage, auth, etc.)
- New conventions are established
- New TypeScript gotchas are discovered

#### 4. `ROADMAP.md` — Add new tasks if discovered

During implementation you may find bugs or missing features not in the xlsx.
Add them to the appropriate phase with a note:

```markdown
### 1.14 `[LIGHT]` Fix z-index on color picker (discovered during 1.02)
```

---

## Session Log Template

Create `SESSION-LOG.md` if it doesn't exist:

```markdown
# ArchiTools — Session Log

> Newest sessions first. Each AI session appends an entry here.

---

## Session — YYYY-MM-DD (Model Name)

### Completed
- Task X.XX: Description of what was done

### In Progress
- Task X.XX: What's partially done, where it stopped

### Blockers
- What's needed from the user

### Notes
- Anything useful for the next session

---
```

---

## Prompt Variants

### For a specific task
```
I'm working on ArchiTools. Read CLAUDE.md and ROADMAP.md.
I want to work on task 1.05 (Mini Utilities — Add Missing Tools).
Pull latest, implement it, build, push, and notify me when done.
```

### For bug fixing
```
I'm working on ArchiTools. Read CLAUDE.md.
There's a bug: [describe the bug].
Pull latest, investigate, fix it, build, push.
Don't change anything else.
```

### For code review
```
I'm working on ArchiTools. Read CLAUDE.md.
Review the last commit on main. Check for:
- TypeScript strict mode issues
- Missing null guards
- UI text in Romanian
- Unused imports
Don't change anything, just report findings.
```

### For starting a brand new module
```
I'm working on ArchiTools. Read CLAUDE.md and ROADMAP.md.
I want to build [Module Name] as described in task X.XX.
Read the existing module pattern in src/modules/registratura/ as reference.
Follow the same structure: types.ts, config.ts, services/, hooks/, components/, index.ts.
Build, test, push, notify me.
```

---

## Tips for Smooth Handoffs

1. **Always pull before starting** — another session may have pushed changes
2. **Always push before ending** — don't leave uncommitted work
3. **Update SESSION-LOG.md** — the next AI has no memory of this session
4. **Mark tasks in ROADMAP.md** — ✅ with date is the source of truth
5. **Don't skip tasks** — they're ordered by dependency
6. **Ask the user if blocked** — don't guess on design decisions
7. **One task at a time** — implement, build, push, get approval, then next
8. **Commit messages follow convention** — `feat(module):`, `fix(module):`, `docs:`