ArchiTools/SESSION-GUIDE.md

ArchiTools — Session Guide for AI Assistants

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

---

Project Location

What	Where
Gitea repo	http://10.10.10.166:3002/gitadmin/ArchiTools
Branch	main
Local path (Mac)	/Users/mariustarau/Development/ArchiTools
Production	http://10.10.10.166:3000
Dev server	http://localhost:3000

Key Files (all in repo root)

File	What it does	Read when
CLAUDE.md	Project context, stack, architecture, conventions	Every session start
ROADMAP.md	Complete task list — tasks with ✅ are done, others are pending	Every session start
SESSION-LOG.md	What was done in each previous session	Every session start
SESSION-GUIDE.md	This file — prompts, workflow, rules	First time only

---

Prompt: Starting a Brand New Session

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

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

Repo: http://10.10.10.166:3002/gitadmin/ArchiTools (branch: main)
Local path: /Users/mariustarau/Development/ArchiTools

Read these files from the repo root first (in this order):
1. /Users/mariustarau/Development/ArchiTools/CLAUDE.md — project context, stack, architecture
2. /Users/mariustarau/Development/ArchiTools/ROADMAP.md — task list (tasks with ✅ are done, pick the next one without ✅)
3. /Users/mariustarau/Development/ArchiTools/SESSION-LOG.md — what previous sessions did
4. /Users/mariustarau/Development/ArchiTools/SESSION-GUIDE.md — workflow rules

Start by running: git pull origin main && npm install
Then pick the next uncompleted task from ROADMAP.md (top to bottom, skip ✅ tasks).

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

---

Prompt: Resuming Where You Left Off

I'm continuing work on ArchiTools.

Repo: http://10.10.10.166:3002/gitadmin/ArchiTools (branch: main)
Local path: /Users/mariustarau/Development/ArchiTools

Read these files first:
1. /Users/mariustarau/Development/ArchiTools/CLAUDE.md — project context
2. /Users/mariustarau/Development/ArchiTools/ROADMAP.md — find the next task without ✅
3. /Users/mariustarau/Development/ArchiTools/SESSION-LOG.md — see what was done before

Run: git pull origin main && npm install
Then continue with the next uncompleted task from ROADMAP.md.

Same rules: build must pass, push when done, update ROADMAP.md and SESSION-LOG.md,
notify me for review on http://10.10.10.166:3000 before moving to next task.

---

Prompt: Specific Task

I'm working on ArchiTools.
Local path: /Users/mariustarau/Development/ArchiTools

Read /Users/mariustarau/Development/ArchiTools/CLAUDE.md and
/Users/mariustarau/Development/ArchiTools/ROADMAP.md first.

Run: git pull origin main && npm install
Then work on task [NUMBER] ([TASK NAME]) from ROADMAP.md.

Implement it, run `npx next build` (must pass), push to main,
update ROADMAP.md (✅ + date) and SESSION-LOG.md, then notify me.

---

Prompt: Bug Fix

I'm working on ArchiTools.
Local path: /Users/mariustarau/Development/ArchiTools

Read /Users/mariustarau/Development/ArchiTools/CLAUDE.md first.

Run: git pull origin main
There's a bug: [DESCRIBE THE BUG].
Investigate, fix it, run `npx next build`, push to main.
Don't change anything unrelated to the bug.
Update SESSION-LOG.md with what you fixed.

---

Prompt: Code Review (no changes)

I'm working on ArchiTools.
Local path: /Users/mariustarau/Development/ArchiTools

Read /Users/mariustarau/Development/ArchiTools/CLAUDE.md first.

Run: git pull origin main
Review the last 3 commits on main. Check for:
- TypeScript strict mode issues
- Missing null guards on Record/array access
- UI text that should be in Romanian
- Unused imports or dead code
- Security issues (XSS, injection)
Don't change anything, just report findings.

---

Prompt: New Module from Scratch

I'm working on ArchiTools.
Local path: /Users/mariustarau/Development/ArchiTools

Read /Users/mariustarau/Development/ArchiTools/CLAUDE.md and
/Users/mariustarau/Development/ArchiTools/ROADMAP.md first.

Run: git pull origin main && npm install
I want to build [MODULE NAME] as described in task [NUMBER] of ROADMAP.md.

Read the module pattern in /Users/mariustarau/Development/ArchiTools/src/modules/registratura/
as reference. Follow the same structure:
  types.ts, config.ts, services/, hooks/, components/, index.ts

Also create:
  src/app/(modules)/[route]/page.tsx
  Update src/config/modules.ts, navigation.ts, flags.ts

Run `npx next build`, push to main, update ROADMAP.md + SESSION-LOG.md, notify me.

---

Git Workflow

First time (clone)

git clone http://10.10.10.166:3002/gitadmin/ArchiTools.git
cd ArchiTools
npm install
npm run dev    # http://localhost:3000

Every session start (pull)

cd /Users/mariustarau/Development/ArchiTools
git pull origin main
npm install
npm run dev

After completing work (push)

npx next build                    # MUST pass with zero errors
git add <specific-files>          # never git add -A
git commit -m "feat(module): description

Co-Authored-By: <model-name>"
git push origin main              # auto-deploys to http://10.10.10.166:3000

---

Files to Keep Updated After Every Session

1. ROADMAP.md — Mark completed tasks

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

2. SESSION-LOG.md — Add entry at the TOP

## Session — 2026-02-18 (Sonnet 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

### Blockers
- Need US/SDT logo files from user

### Notes
- Build passes, pushed commit abc1234
---

3. CLAUDE.md — Only if architecture changes

Update when: new module added, core system changed, new conventions, new TS gotchas.

4. ROADMAP.md — Add new tasks if discovered during work

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

---

Tips for Smooth Handoffs

1. Always pull before starting — another session may have pushed
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 — feat(module):, fix(module):, docs: