docs: rewrite JavaScript SDK first-use guide

[daniel-scrivner]

Summary

Rewrites the public JavaScript SDK README around one useful first success: install the package, retrieve Apple's latest 10-K, inspect the source-linked response, and understand what to do next. It also corrects standalone repository commands and package discovery metadata.

Linear: OMNI-5200

Scope

• src/ — SDK source (client, types, resources)
• test/ — Test suite
• examples/ — Example programs
• package.json / dependencies
• tsconfig.json / tsconfig.build.json — TS config
• README.md / docs
• .github/ — CI/CD workflows
• Build / publish config

Changes

• Leads with installation, a runnable agentLatestFiling request, and a production-verified compact response with SEC accession and source URL.
• Reorganizes authentication, errors, pagination, retries, streams, and contributing material beneath the first successful request.
• Removes monorepo-only commands and internal-facing copy from the public README.
• Replaces the dead support URL, sharpens npm description copy, and declares Node.js 18+ compatibility.

Verification

bun install --frozen-lockfile  # passed
bun run typecheck              # passed
bun test                       # passed: 93 tests
bun run build                  # passed

Additional verification

npm pack --dry-run --json --ignore-scripts  # passed: 42 files, README included
SECAPI_API_KEY=... bun run examples/agent_workflow.ts
# passed live: Apple entity, latest 10-K, Item 1A with 1,600-character compact content

Three GPT-5.5 High adversarial reviewers covered factual accuracy, editorial quality, and developer experience. Round one findings were addressed; round two passed at 93/100 editorial quality with no blocking findings.

Deployment Impact

• New version bump in package.json
• Breaking API change (semver major)
• npm publish required
• Docs (README / examples) updated to match
• Companion docs PR in secapi-ai org docs site

GitHub will show the README after merge. The npm package page will show the new README and metadata with the next package publish.

Completion Attestation

• 100% complete, 100% functional. All scoped source changes are written, tested, typecheck, build cleanly, and work end-to-end against live SEC API. No source work remains in this PR.
• Not fully complete or functional. Deltas listed below.

Demo

The checked-in live example returned Apple Inc. (AAPL, CIK 0000320193), accession 0000320193-25-000079, filing date 2025-10-31, and a compact Item 1A result with non-empty content.

---

Agent Context

Key files to read first:

• README.md
• package.json
• src/index.ts
• examples/agent_workflow.ts

Decisions made:

• The opening example uses agentLatestFiling because it yields the smallest source-linked result a new user can verify.
• Reliability detail remains documented, but no longer blocks the first request.
• Package metadata changes intentionally wait for the normal next version publish.

Relevant docs:

• README.md
• https://docs.secapi.ai

Conventions applied:

• External-user-first prose
• Claims checked against implementation, tests, live API output, and SEC source metadata
• ESM and API-version behavior stated explicitly

[Copilot]

Pull request overview

This PR rewrites the public-facing JavaScript SDK README to lead with a first successful request workflow (install → fetch Apple’s latest 10‑K → inspect a source-linked compact response), and updates npm package metadata to better reflect supported runtimes and support links.

Changes:

• Restructures README.md around a “first request” path, then organizes common usage topics (pagination, errors, auth, retries, streams, contributing).
• Updates package.json package description, adds a Node.js engines constraint (18+), and replaces the bugs/support URL with GitHub Issues.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
README.md	Rewritten first-use guide and reorganized operational docs (auth, retries, streams, etc.).
package.json	Updates npm metadata (description, Node engines, bugs URL) to match the public SDK positioning.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.