gws-docs

gws-docs is a thin reusable layer on top of gws for AI agents that need to create formatted Google Docs and place them in Google Drive predictably.

Read This First If You Are An AI Agent

If you have zero context, follow these rules exactly:

1. Do not handcraft raw Google Docs API indexes or raw gws docs batchUpdate requests unless you are explicitly modifying this tool itself.
2. Write document content as a JSON spec.
3. Pass the destination folder at runtime with --folder-id or --folder-name unless the task is a fixed automation.
4. Run gws-docs render <spec.json> ....
5. Return the resulting documentId, folderId, and title.

If gws-docs is available, prefer it over custom one-off Docs rendering logic.

What This Tool Does

This tool takes a simple structured JSON spec and does the low-level work for you:

1. Creates a Google Doc through gws
2. Inserts the content
3. Applies consistent formatting
4. Resolves or creates the destination Drive folder
5. Moves the Doc into that folder

What This Tool Does Not Do

• It does not authenticate Google Workspace for you
• It does not store or ship credentials
• It does not infer missing required content
• It does not support every possible Google Docs layout yet

If you need unsupported formatting, extend the schema and renderer instead of bypassing the tool silently.

Requirements

• gws must already be installed on the local machine
• gws must already be authenticated locally, for example with gws auth login
• Google credentials stay local to the machine
• This package does not contain OAuth client secrets, access tokens, or refresh tokens

Install / Run

If the binary is installed globally:

gws-docs render ./spec.json --folder-name "My Documents"

If you are running from a cloned repo:

node ./cli.mjs render ./spec.json --folder-name "My Documents"

Use a stable Drive folder ID when you already know it:

gws-docs render ./spec.json --folder-id "<DRIVE_FOLDER_ID>"

Exact CLI Contract

gws-docs render <spec.json> [--folder-id <id>] [--folder-name <name>] [--parent-id <id>]

Rules:

• Pass --folder-id or --folder-name, not both
• If both the spec and CLI provide a destination, CLI wins
• --parent-id only matters when the tool needs to create a folder by name
• If no destination exists in either the spec or CLI, rendering fails

Fastest Safe Workflow For Agents

When you need to create a document, do this:

1. Read this README once
2. Inspect examples/ai-workflow-spec.json
3. Write a new JSON spec
4. Prefer runtime destination flags instead of hardcoding Drive-specific values into the spec
5. Render the doc
6. Return the JSON result from stdout

Expected Output

Successful runs print JSON like this:

{
  "documentId": "1abc...",
  "folderId": "1def...",
  "title": "Project Brief",
  "destination": "My Documents"
}

Return those values to the user or calling agent.

Supported Formatting Features

• Title
• Optional subtitle
• Section headings using HEADING_1 to HEADING_6
• Paragraph blocks
• Bulleted lists
• Numbered lists
• Key/value reference blocks with bold labels
• Destination folder by Drive folder ID
• Destination folder by folder name with auto-create

JSON Spec Contract

Top-level fields:

• title required string
• subtitle optional string
• destination optional object if the destination will be passed at runtime
• sections required non-empty array

Section fields:

• heading required string
• level optional integer from 1 to 6
• blocks required non-empty array

Supported block types:

• paragraph
• bullet_list
• numbered_list
• key_value

Minimal Spec

{
  "title": "Document title",
  "sections": [
    {
      "heading": "Summary",
      "level": 1,
      "blocks": [
        {
          "type": "paragraph",
          "text": "Write the summary here."
        }
      ]
    }
  ]
}

Full Example Shape

{
  "title": "Document title",
  "subtitle": "Optional subtitle",
  "destination": {
    "folderName": "My Documents"
  },
  "sections": [
    {
      "heading": "Executive Summary",
      "level": 1,
      "blocks": [
        {
          "type": "paragraph",
          "text": "Write normal text here."
        },
        {
          "type": "bullet_list",
          "items": ["One", "Two"]
        },
        {
          "type": "numbered_list",
          "items": ["Step one", "Step two"]
        },
        {
          "type": "key_value",
          "items": [
            { "label": "Owner", "value": "AI agent" }
          ]
        }
      ]
    }
  ]
}

Destination Rules

Preferred order:

1. Use --folder-id when the caller already knows the exact Drive folder
2. Use --folder-name when the tool should find or create the folder
3. Put destination inside the spec only for fixed workflows or automations

This keeps specs reusable across users, repos, and environments.

Failure Modes

A run will fail if:

• gws is not installed
• gws is not authenticated
• the spec JSON is invalid
• the spec is missing required fields
• no destination is provided
• both --folder-id and --folder-name are provided

When it fails, fix the input or environment. Do not fall back to raw Docs API logic unless you are intentionally extending gws-docs.

Example Commands

Render using a folder name:

gws-docs render ./examples/ai-workflow-spec.json --folder-name "Agent Output"

Render using a folder ID:

gws-docs render ./examples/ai-workflow-spec.json --folder-id "1abc123..."

Render from this repo directly:

node ./cli.mjs render ./examples/ai-workflow-spec.json --folder-name "Agent Output"

Example Instructions For Another Agent

Use this exact instruction pattern:

Use `gws-docs` to create the Google Doc. Do not handcraft raw Google Docs API requests.

Steps:
1. Read the gws-docs README.
2. Create a JSON spec for the requested document.
3. Pass the destination at runtime with --folder-id or --folder-name.
4. Run gws-docs render.
5. Return documentId, folderId, title, and the spec file path.

Design Principle

This tool exists to separate:

• content generation
• formatting/rendering
• Drive placement

That separation is the main value. It makes agent behavior more reliable, more reusable, and easier to improve later.

Public Package Model

The intended deployment model is:

• gws-docs code is shared publicly as a normal package or GitHub repo
• each machine keeps its own local gws credentials
• agents call the installed gws-docs binary
• Drive destination is passed at runtime

That gives you a shared renderer without sharing tokens or hardcoding machine-specific paths.