Refactor README.md for 2025-10, fix build-and-publish-docs workflow (#375)

## Problem
The typescript client's README has become quite bloated over time.
There's a lot of dense information stuffed into the top-level
`README.md` file which is not always conducive to people getting up and
running quickly, or finding information easily.

The `build-and-publish-docs` workflow is also not being run from the
`release` workflow due to recent changes to align with npm's new
[trusted publishing model](https://docs.npmjs.com/trusted-publishers).
Because we now have `environment: npm-publish` associated with the
release workflow/job, we need to handle secrets differently when passing
them to other jobs such as `integration-tests` and
`build-and-publish-docs`.

## Solution
Break the Typescript README up into a `/guides` folder struct (similar
to what was done in the [python
repo](https://github.com/pinecone-io/pinecone-python-client/tree/main/docs)).
The top-level repo `README` is more succinct, with a focus on getting up
and running quickly with client. We then use links to the nested
`guides/` markdown files for more specific examples and info.

**New Structure**
```
guides/
├── README.md                           # Navigation hub for all guides
├── faq.md                              # Frequently asked questions
│
├── index-management/
│   ├── serverless-indexes.md          # Creating and managing serverless indexes
│   ├── pod-indexes.md                 # Creating and managing pod-based indexes
│   ├── collections.md                 # Working with collections
│   ├── backups.md                     # Backup and restore operations
│   └── shared-operations.md           # Operations common to all index types
│
├── data-operations/
│   ├── working-with-vectors.md        # Upsert, query, fetch, update, delete
│   ├── namespaces.md                  # Namespace management
│   ├── metadata-filtering.md          # Filtering records by metadata
│   └── bulk-import.md                 # Importing large datasets from object storage
│
├── inference/
│   ├── inference-api.md               # Standalone embedding and reranking
│   └── integrated-inference.md        # Index-integrated inference operations
│
├── assistant/
│   ├── getting-started.md             # Creating and targeting assistants
│   ├── chat.md                        # Chat operations and streaming
│   └── file-management.md             # Upload, list, and manage files
│
├── typescript-features/
│   ├── type-safety.md                 # Leveraging generics for type safety
│   ├── async-patterns.md              # Async/await patterns and concurrency
│   └── error-handling.md              # Error handling best practices
│
└── upgrading/
    ├── v2-migration.md                # Migration guide: v1.x → v2.x
    └── v1-migration.md                # Migration guide: v0.x → v1.x
```

Additionally, I've updated the `release.yml` workflow to explicitly pass
secrets (`PINECONE_API_KEY` / `VERCEL_TOKEN`) to the child workflows:
`integration-tests`, and `build-and-publish-docs`.

Hopefully, this resolves the skipped workflows when running the release.

Also updated some doc comments and test cruft to clean some additional
things up.

## Type of Change
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to not work as expected)
- [ ] This change requires a documentation update
- [X] Infrastructure change (CI configs, etc)
- [X] Non-code change (docs, etc)
- [ ] None of the above: (explain here)

## Test Plan
These changes are all documentation and infrastructure related. In order
to test the release flow properly, we'll need to re-run a release and
see if the child workflows are properly triggered with secrets. It's
possible we may need to reconfigure the secrets for the repo to live
inside of the `npm-publish` environment.


<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Medium risk because it changes GitHub Actions secret wiring for
reusable workflows, which could break releases/CI if environment secrets
are misconfigured; documentation changes are otherwise low risk.
> 
> **Overview**
> **Docs overhaul:** Replaces the bloated top-level `README.md` with a
shorter quickstart-focused version and links out to a new structured
`guides/` documentation tree (index management, data ops, inference,
assistant, TS features, FAQ, upgrading).
> 
> **CI fix:** Updates reusable workflow secret requirements by adding
`VERCEL_TOKEN` to `pr.yml`’s `workflow_call` secrets and changing
`release.yml` to explicitly pass required secrets to the
`integration-tests` and `build-and-publish-docs` reusable workflows
instead of `secrets: inherit`.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
3b2bd09. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---
- To see the specific tasks where the Asana app for GitHub is being
used, see below:
  - https://app.asana.com/0/0/1213055949284764

Author: austin-denoble

.github/workflows/pr.yml

@@ -15,6 +15,8 @@ on:
     secrets:
       PINECONE_API_KEY:
         required: true
+      VERCEL_TOKEN:
+        required: true
 
 permissions:
   contents: read

.github/workflows/release.yml

@@ -53,7 +53,9 @@ jobs:
   integration-tests:
     if: ${{ github.event.inputs.runTests == 'true' }}
     uses: ./.github/workflows/pr.yml
-    secrets: inherit
+    secrets:
+      PINECONE_API_KEY: ${{ secrets.PINECONE_API_KEY }}
+      VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
     with:
       ref: ${{ inputs.ref }}
 
@@ -191,6 +193,7 @@ jobs:
     needs: version-and-release
     if: ${{ github.event.inputs.releaseMode == 'prod' && needs.version-and-release.result == 'success' }}
     uses: ./.github/workflows/build-and-publish-docs.yml
-    secrets: inherit
+    secrets:
+      SSH_DEPLOY_KEY: ${{ secrets.SSH_DEPLOY_KEY }}
     with:
       ref: ${{ github.event.inputs.ref }}

README.md

@@ -0,0 +1,46 @@
+# Pinecone TypeScript SDK Documentation
+
+Detailed guides for using the Pinecone TypeScript SDK.
+
+## Index Management
+
+- [Serverless Indexes](./index-management/serverless-indexes.md) - Create and manage auto-scaling serverless indexes
+- [Pod Indexes](./index-management/pod-indexes.md) - Create and manage dedicated pod-based indexes
+- [Collections](./index-management/collections.md) - Static copies of pod-based indexes
+- [Backups](./index-management/backups.md) - Create and restore from serverless index backups
+- [Common Operations](./index-management/shared-operations.md) - List, describe, delete, and configure indexes
+
+## Data Operations
+
+- [Working with Vectors](./data-operations/working-with-vectors.md) - Upsert, query, fetch, update, and delete vectors
+- [Namespaces](./data-operations/namespaces.md) - Organize vectors within an index
+- [Metadata Filtering](./data-operations/metadata-filtering.md) - Advanced filtering with operators
+- [Bulk Import](./data-operations/bulk-import.md) - Import large datasets from object storage
+
+## Inference
+
+- [Inference API](./inference/inference-api.md) - Use standalone embedding and reranking models
+- [Integrated Inference](./inference/integrated-inference.md) - Index-integrated embedding and reranking
+
+## Assistant
+
+- [Getting Started](./assistant/getting-started.md) - Quick start guide for Pinecone Assistant
+- [Chat Operations](./assistant/chat.md) - Chat, streaming, and context retrieval
+- [File Management](./assistant/file-management.md) - Upload, list, and manage files
+
+## TypeScript Features
+
+- [Type Safety](./typescript-features/type-safety.md) - Generic metadata types and type-safe operations
+- [Async Patterns](./typescript-features/async-patterns.md) - Best practices for async/await
+- [Error Handling](./typescript-features/error-handling.md) - Error types and recovery strategies
+
+## Upgrading
+
+- [v2 Migration Guide](./upgrading/v2-migration.md) - Upgrading from v1.x to v2.x
+- [v1 Migration Guide](./upgrading/v1-migration.md) - Upgrading from v0.x to v1.x
+
+## Additional Resources
+
+- [FAQ](./faq.md) - Frequently asked questions and troubleshooting
+- [API Reference](https://sdk.pinecone.io/typescript/classes/Pinecone.html) - Complete TypeDoc API documentation
+- [Official Docs](https://docs.pinecone.io) - Conceptual guides and tutorials