Update projects docs with DataFrame API and data source details

- Update examples to show DataFrame default output
- Add "How it works" section explaining the portal API and PRJ resolution
- Fix pi field description (now a display name string, not dict)

Author: kks32

docs/projects.md

@@ -1,49 +1,58 @@
 # Projects
 
+DesignSafe projects (MyProjects) are collaborative workspaces where team members share files, curate datasets, and publish research. Each project has a PRJ number (e.g., PRJ-6270), a UUID, and a corresponding Tapis storage system.
+
+Project metadata is fetched from the [DesignSafe portal API](https://designsafe-ci.org) (`/api/projects/v2/`), which provides project details, team information, and DOIs. File listings use the Tapis Files API against the project's storage system (`project-<uuid>`).
+
 ## List your projects
 
+Returns a DataFrame by default. Use `output="list"` for a list of dicts.
+
 ```python
 from dapi import DSClient
 ds = DSClient()
 
-projects = ds.projects.list()
-for p in projects[:5]:
-    pi = p['pi']
-    pi_name = f"{pi['fname']} {pi['lname']}" if pi else "N/A"
-    print(f"{p['projectId']:12s} | {pi_name:25s} | {p['title'][:50]}")
+# DataFrame (renders as a table in Jupyter)
+ds.projects.list()
+
+# List of dicts
+projects = ds.projects.list(output="list")
 ```
 
 Pagination:
 
 ```python
-# Get projects 100-199
-projects = ds.projects.list(limit=100, offset=100)
+ds.projects.list(limit=100, offset=100)
 ```
 
+DataFrame columns: `projectId`, `title`, `pi`, `type`, `created`, `lastUpdated`, `uuid`.
+
 ## Get project details
 
+Returns a dictionary with full project metadata.
+
 ```python
 info = ds.projects.get("PRJ-6270")
 
-print(info['title'])
-print(info['description'])
-print(info['projectType'])
-print(info['pi'])
-print(info['dois'])
-print(info['keywords'])
-print(info['awardNumbers'])
-print(info['systemId'])  # Tapis system ID for file access
+info['title']
+info['description']
+info['pi']           # PI display name (e.g., "Cheng-Hsi Hsiao")
+info['dois']         # Associated DOIs
+info['keywords']
+info['awardNumbers']
+info['projectType']  # experimental, simulation, field_recon, other, etc.
+info['systemId']     # Tapis system ID for file access
 ```
 
-The returned dictionary contains:
+Full field reference:
 
 | Field | Description |
 |---|---|
 | `uuid` | Project UUID |
 | `projectId` | Project ID (e.g., "PRJ-6270") |
 | `title` | Project title |
 | `description` | Project description |
-| `pi` | Principal investigator (dict with username, fname, lname, email) |
+| `pi` | Principal investigator display name |
 | `coPis` | Co-PIs |
 | `teamMembers` | Team members |
 | `awardNumbers` | Grant/award numbers |
@@ -56,18 +65,21 @@ The returned dictionary contains:
 
 ## List files in a project
 
+Returns a DataFrame by default. Use `output="raw"` for Tapis file objects.
+
 ```python
 # Root of a project
-files = ds.projects.files("PRJ-6270")
-for f in files:
-    print(f"{f.name:50s} {f.type}")
+ds.projects.files("PRJ-6270")
 
 # Subfolder
-files = ds.projects.files("PRJ-1305", path="/Training/")
-for f in files[:10]:
-    print(f"{f.name:50s} {f.type}")
+ds.projects.files("PRJ-1305", path="/Training/")
+
+# Raw Tapis file objects
+files = ds.projects.files("PRJ-6270", output="raw")
 ```
 
+DataFrame columns: `name`, `type`, `size`, `lastModified`, `path`.
+
 ## Projects and file path translation
 
 `ds.files.to_uri()` also accepts project paths. dapi resolves the PRJ number to the Tapis system UUID automatically:
@@ -81,6 +93,14 @@ files = ds.files.list(uri)
 
 Both `/MyProjects/PRJ-XXXX/` and `/projects/PRJ-XXXX/` are accepted.
 
+## How it works
+
+1. **Project listing and metadata** — dapi queries the DesignSafe portal API (`https://designsafe-ci.org/api/projects/v2/`) using your Tapis authentication token. This API returns project metadata including the project UUID.
+
+2. **PRJ-to-UUID resolution** — Each project's Tapis storage system ID is `project-<uuid>`. When you use a PRJ number (e.g., `PRJ-6270`), dapi looks up the UUID via the portal API.
+
+3. **File operations** — File listings use the standard Tapis Files API (`t.files.listFiles`) against the resolved `project-<uuid>` system.
+
 ## Error handling
 
 - **Project not found**: raised if the PRJ number doesn't match any project you have access to.