docs: Add Folder Management API to Unstable spec (#387)

* Add Internal Articles Folders API to Unstable version

- Add folder_id field to internal_article schema (nullable)
- Add folder_id parameter to create internal article request
- Add folder_id query parameter to search endpoint (already present)
- Add new endpoints:
  * GET /internal_articles/folders - List all folders
  * POST /internal_articles/folders - Create a folder
  * GET /internal_articles/folders/{id} - Get folder details
  * PUT /internal_articles/folders/{id} - Update a folder
  * DELETE /internal_articles/folders/{id} - Delete empty folder
  * POST /internal_articles/move_to_folder - Bulk move articles

- Add schemas:
  * internal_article_folder
  * internal_article_folder_list
  * create_internal_article_folder_request
  * update_internal_article_folder_request

This enables folder management for internal articles through the API,
allowing customers to organize their internal documentation.

Relates to: intercom/intercom#472943

* docs: Refactor folder endpoints to top-level /folders

Update OpenAPI specification to reflect folder endpoints moving from
/internal_articles/folders to top-level /folders resource.

Changes:
- Update paths: /internal_articles/folders → /folders
- Update operation IDs: Remove "InternalArticle" prefix
- Change tags: "Internal Articles" → "Folders"
- Update descriptions: Remove "for internal articles" references
- Remove bulk move endpoint /internal_articles/move_to_folder

This makes folders a first-class organizational structure that can be
used across multiple content types, not just internal articles.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: Update Folders API and add folder_id to article schemas

- Add parent_folder_id query param to GET /folders for hierarchy filtering
- Rename article_count to content_count to match monolith presenter
- Add folder_id to article_list_item, create/update article requests
- Add folder_id to update_internal_article_request
- Add phrase query param and fix folder_id type on internal articles search
- Add deleted_folder_object schema for delete response
- Fix owner_id description in update_internal_article_request

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: Rename folder schemas to first-class resource naming

Folders are a top-level resource that can hold both articles and internal
articles. Rename internal_article_folder* schemas to folder* to reflect this.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: Remove phrase param, inline folder request/list schemas

- Remove phrase query param from internal articles search (not implemented)
- Inline folder_list, create_folder_request, update_folder_request schemas
  directly into endpoint definitions instead of separate schema refs
- Remove standalone schema definitions for the above
- Keep folder and deleted_folder_object as reusable schemas

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: Add missing error responses (401, 422) to folder endpoints

Add 401 Unauthorized to Create, Retrieve, Update, Delete folder endpoints.
Add 422 Validation error to Update folder endpoint.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: Use 400 for validation errors, reserve 422 for delete conflict

Create and Update folder endpoints now return 400 Bad Request for
validation errors. 422 is reserved for Delete when folder has content.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: sametozcan