pi-revit 0.1.7 → 0.1.8

package/README.md

@@ -115,16 +115,16 @@ That's all. Pi starts with the Revit tools ready:
 `pi` command itself. That folder is on your system PATH — which is exactly why *every* terminal
 finds `pi-revit`, with no extra configuration. When you run it, it switches to your workspace at
 `Documents\pi-revit` and starts Pi there, so your conventions file (`AGENTS.md`) loads
-automatically and all Revit session history lives in one predictable place. The Revit tools
-themselves are installed globally in Pi, and the extension discovers them live from the bridge
-inside Revit each time a session starts.
+automatically and all Revit session history lives in one predictable place (`pi-revit -c`
+continues the last session). The Revit tools themselves are installed globally in Pi, and the
+extension discovers them live from the bridge inside Revit each time a session starts.
 
-**Per project:** create one subfolder per Revit project under `Documents\pi-revit\Projects\`:
-
-```powershell
-pi-revit tower-b        # Pi scoped to that project — its notes and its session history
-pi-revit tower-b -c     # continue that project's last session
-```
+**Per model, automatically:** files sort themselves. Exports land in
+`Documents\pi-revit\Models\<model title>\exports` — the add-in derives the folder from the
+document being exported, so even a session that touches many models files every output under
+the right one, with no naming decision from you or the AI. Each model folder carries a
+`model.txt` recording the model's GUID and file path, so two models that share a title stay
+distinguishable.
 
 Plain `pi` from any folder also works; `pi-revit` just adds the right working folder on top.
 
@@ -142,7 +142,7 @@ Plain `pi` from any folder also works; `pi-revit` just adds the right working fo
 | `search_api_docs` | Search the offline Revit API docs (works with no document open) |
 | `execute_csharp` | Run a C# script in one auto-managed transaction — the escape hatch |
 | `capture_view` | PNG snapshot of a view to a temp file (read the returned path to see it) |
-| `export_documents` | PDF/DWG/PNG/IFC export of sheets and views |
+| `export_documents` | PDF/DWG/PNG/IFC export of sheets and views — auto-sorted into `Models\<model>\exports` |
 | `get_model_health` | Warnings grouped + worksets, phases, design options audit |
 
 ## Limitations — read before using on real projects

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-revit",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Native Pi connector for Autodesk Revit. Run npx.cmd -y pi-revit for the full Windows install.",
   "author": "Ahmad Altahlawi",
   "license": "MIT",

package/scripts/setup-workspace.ps1

@@ -2,12 +2,13 @@
 <#
 Sets up the pi-revit user environment on this PC:
 
-  1. Workspace at Documents\pi-revit (AGENTS.md conventions, Projects\sample template,
-     double-click launcher). Existing AGENTS.md files are never overwritten.
+  1. Workspace at Documents\pi-revit (AGENTS.md conventions, Models\ output tree,
+     double-click launcher). An existing AGENTS.md is never overwritten.
   2. Global `pi-revit` command installed next to the `pi` command, so any terminal can run:
        pi-revit              -> Pi in the workspace
-       pi-revit <project>    -> Pi in Projects\<project>
-       pi-revit <project> -c -> continue that project's last session
+       pi-revit -c           -> continue the last session
+     Model output sorts itself: the Revit tools file each export under
+     Models\<model title>\ automatically, keyed by the document it came from.
 
 Idempotent — safe to re-run. Usage:
   scripts\setup-workspace.ps1
@@ -20,18 +21,14 @@ param(
 $ErrorActionPreference = 'Stop'
 $templates = Join-Path (Split-Path $PSScriptRoot -Parent) 'workspace'
 
-# 1. Workspace folders
-New-Item -ItemType Directory -Force -Path (Join-Path $WorkspaceDir 'Projects\sample') | Out-Null
+# 1. Workspace folders. Models\ is where the Revit tools file per-model output.
+New-Item -ItemType Directory -Force -Path (Join-Path $WorkspaceDir 'Models') | Out-Null
 
 # Conventions / notes: copy only when missing so user edits survive re-runs.
 $workspaceAgents = Join-Path $WorkspaceDir 'AGENTS.md'
 if (-not (Test-Path $workspaceAgents)) {
     Copy-Item (Join-Path $templates 'AGENTS.md') $workspaceAgents
 }
-$projectAgents = Join-Path $WorkspaceDir 'Projects\sample\AGENTS.md'
-if (-not (Test-Path $projectAgents)) {
-    Copy-Item (Join-Path $templates 'project-AGENTS.md') $projectAgents
-}
 
 # Launcher is code, not user data: always refresh.
 Copy-Item (Join-Path $templates 'pi-revit-here.cmd') (Join-Path $WorkspaceDir 'pi-revit.cmd') -Force
@@ -77,7 +74,7 @@ if ($pi) {
     # localized folder names) stay intact.
     Set-Content -Path (Join-Path $binDir 'pi-revit.cmd') -Value $globalCmd -Encoding Oem
     Write-Host "Global command installed: $(Join-Path $binDir 'pi-revit.cmd')" -ForegroundColor Green
-    Write-Host 'Run pi-revit from any terminal (pi-revit <project> for a project folder).'
+    Write-Host 'Run pi-revit from any terminal (pi-revit -c continues the last session).'
 } else {
     Write-Warning 'No permanent pi command found on PATH. Install Pi first (npm install -g --ignore-scripts @earendil-works/pi-coding-agent), then run npx.cmd -y pi-revit again (or re-run this script) to get the global pi-revit command.'
 }

package/src/Revit/Tools/ExportDocuments.cs

@@ -19,7 +19,7 @@ namespace RevitBridge.Tools
 
         public string Name => "export_documents";
         public string Label => "Export Documents";
-        public string Description => "Export documents from the open Revit model. format 'pdf'/'dwg'/'png' export the given sheet/view ids to files: pdf combines everything into one file by default (combine=false writes one PDF per sheet/view, named by Revit's naming rule); png renders 2048 px wide; ifc exports the whole model, or just what one given view shows. Files land in output_dir (created if missing; default: a fresh folder under the system temp directory); file_name_prefix sets the base file name (default: the document title; Revit appends view/sheet suffixes for multi-file exports). Returns the produced file paths with sizes. Find sheet/view ids with get_elements (category 'Sheets' or 'Views') first.";
+        public string Description => "Export documents from the open Revit model. format 'pdf'/'dwg'/'png' export the given sheet/view ids to files: pdf combines everything into one file by default (combine=false writes one PDF per sheet/view, named by Revit's naming rule); png renders 2048 px wide; ifc exports the whole model, or just what one given view shows. Files sort themselves per model: with output_dir omitted they land in Documents\\pi-revit\\Models\\<model title>\\exports, derived from the document being exported (pass output_dir only for a different explicit target); file_name_prefix sets the base file name (default: the document title; Revit appends view/sheet suffixes for multi-file exports). Returns the produced file paths with sizes. Find sheet/view ids with get_elements (category 'Sheets' or 'Views') first.";
         public bool Write => true;
         public string Tier => "advanced";
 
@@ -43,7 +43,7 @@ namespace RevitBridge.Tools
                 output_dir = new
                 {
                     type = "string",
-                    description = "Output directory, created if missing. Default: a fresh folder under the system temp directory.",
+                    description = "Output directory, created if missing. Default: Documents\\pi-revit\\Models\\<model title>\\exports — files sort under the exported model automatically; omit unless the user names a different target.",
                 },
                 file_name_prefix = new
                 {
@@ -74,7 +74,7 @@ namespace RevitBridge.Tools
                 throw new ArgumentException($"Unknown format: {JsonArgs.GetString(args, "format")}. Supported: pdf, dwg, png, ifc.");
 
             var views = ResolveViews(doc, args, format);
-            string outputDir = ResolveOutputDir(args);
+            string outputDir = ResolveOutputDir(args, doc);
             string? prefixInput = JsonArgs.GetString(args, "file_name_prefix");
             string baseName = SanitizeFileName(string.IsNullOrWhiteSpace(prefixInput) ? doc.Title : prefixInput.Trim());
             bool combine = JsonArgs.GetBool(args, "combine", true);
@@ -236,16 +236,48 @@ namespace RevitBridge.Tools
             return views;
         }
 
-        private static string ResolveOutputDir(JsonElement args)
+        private static string ResolveOutputDir(JsonElement args, Document doc)
         {
             string? requested = JsonArgs.GetString(args, "output_dir");
             string outputDir = string.IsNullOrWhiteSpace(requested)
-                ? Path.Combine(Path.GetTempPath(), "revit_export_" + Guid.NewGuid().ToString("N"))
+                ? Path.Combine(ModelFolder(doc), "exports")
                 : Path.GetFullPath(requested.Trim());
             Directory.CreateDirectory(outputDir);
             return outputDir;
         }
 
+        /// <summary>Per-model folder under the pi-revit workspace:
+        /// Documents\pi-revit\Models\&lt;model title&gt;. The exporting tool is the one
+        /// component that knows with certainty which model a file belongs to, so the
+        /// sorting is automatic — never an agent or user decision. model.txt records
+        /// the model's identity so same-titled models stay distinguishable.</summary>
+        private static string ModelFolder(Document doc)
+        {
+            string workspace = Path.Combine(
+                Environment.GetFolderPath(Environment.SpecialFolder.MyDocuments), "pi-revit");
+            string title = SanitizeFileName(string.IsNullOrWhiteSpace(doc.Title) ? "untitled" : doc.Title);
+            string folder = Path.Combine(workspace, "Models", title);
+            Directory.CreateDirectory(folder);
+            TryRecordModelIdentity(folder, doc);
+            return folder;
+        }
+
+        private static void TryRecordModelIdentity(string folder, Document doc)
+        {
+            try
+            {
+                string guid = doc.ProjectInformation?.UniqueId ?? string.Empty;
+                string line = $"{guid}\t{doc.PathName}";
+                string marker = Path.Combine(folder, "model.txt");
+                if (!File.Exists(marker) || !File.ReadAllLines(marker).Contains(line))
+                    File.AppendAllLines(marker, new[] { line });
+            }
+            catch
+            {
+                // The identity record is best-effort; never block an export on it.
+            }
+        }
+
         private static string SanitizeFileName(string name)
         {
             var invalid = Path.GetInvalidFileNameChars();

package/workspace/AGENTS.md

@@ -4,14 +4,32 @@ This folder tree is the working area for Pi + Revit sessions. The pi-revit tools
 Revit bridge add-in; Revit 2025, 2026, or 2027 must be running with a project open
 (only `ping` and `search_api_docs` work without a document).
 
-## Conventions
+## File rules — where every file goes
 
-- One subfolder per Revit project under `Projects\`; start Pi from inside the project folder so
-  sessions, notes, and outputs stay scoped to that project.
-- Save exports, captured view PNGs, scripts, and analysis results inside the current project
-  folder (e.g. an `exports\` subfolder) — not in temp, not in the model's directory.
-- Keep per-project knowledge (naming conventions, known model quirks, decisions) in the project
-  folder's own `AGENTS.md` so every session starts informed.
+Work sorts by model, automatically. The export tool files its output under the model it came
+from — never a decision for you or the user to make:
+
+```text
+Documents\pi-revit\
+├─ AGENTS.md            <- this file
+├─ pi-revit.cmd         <- double-click launcher
+└─ Models\
+   └─ <model title>\    <- created automatically by the tools, one folder per Revit model
+      ├─ model.txt      <- the model's identity (GUID + file path), written by the add-in
+      ├─ exports\       <- export_documents output (its default)
+      ├─ captures\      <- view snapshots worth keeping
+      └─ scripts\       <- generated scripts and analysis for that model
+```
+
+1. **Let exports sort themselves**: call `export_documents` without `output_dir` — files land
+   in `Models\<model title>\exports` automatically, keyed to the exported document. Pass
+   `output_dir` only when the user names a different target.
+2. **Anything else you produce about a model goes into that model's folder**: view captures the
+   user wants to keep in `Models\<model title>\captures` (`capture_view` writes to temp — copy
+   the PNG over; the model title comes from `get_model_overview`), scripts and analysis in
+   `Models\<model title>\scripts`. Create these subfolders on first use.
+3. **Never create files loose in the workspace root.** The root holds `AGENTS.md`,
+   `pi-revit.cmd`, `Models\`, and Pi's own session data — nothing else, ever.
 
 ## Tool habits
 

package/workspace/pi-revit-global.cmd

@@ -1,31 +1,12 @@
-@echo off
-rem pi-revit: open Pi in the pi-revit workspace from anywhere.
-rem   pi-revit              -> Documents\pi-revit (workspace AGENTS.md loads)
-rem   pi-revit <project>    -> Documents\pi-revit\Projects\<project> (its AGENTS.md loads too)
-rem   any further args are passed straight to pi (e.g. pi-revit sample -c)
-rem Installed next to the pi command by scripts\setup-workspace.ps1, which rewrites
-rem the WORKSPACE line below to the chosen -WorkspaceDir.
-
-set "WORKSPACE=%USERPROFILE%\Documents\pi-revit"
-
-if "%~1"=="" (
-    cd /d "%WORKSPACE%"
-    pi
-    exit /b
-)
-
-if exist "%WORKSPACE%\Projects\%~1\" (
-    cd /d "%WORKSPACE%\Projects\%~1"
-    shift
-) else (
-    cd /d "%WORKSPACE%"
-)
-
-set "ARGS="
-:collect
-if not "%~1"=="" (
-    set "ARGS=%ARGS% %1"
-    shift
-    goto collect
-)
-pi%ARGS%
+@echo off
+rem pi-revit: open Pi in the pi-revit workspace from anywhere. All arguments are
+rem passed straight to pi (e.g. pi-revit -c continues the last session).
+rem Model output needs no foldering decision: the Revit tools file each export
+rem under Models\<model title>\ automatically, keyed by the document it came from.
+rem Installed next to the pi command by scripts\setup-workspace.ps1, which rewrites
+rem the WORKSPACE line below to the chosen -WorkspaceDir.
+
+set "WORKSPACE=%USERPROFILE%\Documents\pi-revit"
+
+cd /d "%WORKSPACE%"
+pi %*

package/workspace/project-AGENTS.md

@@ -1,8 +0,0 @@
-# Project: (name)
-
-Notes for Pi sessions on this Revit project. Replace/extend as you learn the model.
-
-- Model: (file name / what it is)
-- Units: (metric/imperial)
-- Naming conventions: (levels, views, sheets)
-- Known quirks: (warnings to ignore, in-place families, etc.)