docs: Fix outdated README sections on API keys, debugging and reloads

[dherault]

Updates the README sections that eight open issues show are wrong or missing. Only the README changes.

Issue	Change
#1608, #1695	"Token authorizers" is now "API keys". It says --apiKey was removed in v11, that keys with a value in provider.apiGateway.apiKeys are accepted, and that a random key is only generated when no key has a value. It includes a stage-based example for a local-only key.
#1657	SLS_DEBUG=* is replaced with --debug, and the sample output now matches v14.
#1810	The "Debug process" section is rewritten. With the Serverless v4 binary, node --inspect serverless and NODE_OPTIONS=--inspect don't reach the framework process. The new recipe opens the inspector via --preLoadModules "$PWD/start-debugger.mjs". The preLoadModules option now says that entries are resolved from the plugin, so local files need an absolute path.
#1659, #1660	New "Reloading handlers after code changes" section, covering reloadHandler, the offline:functionsUpdated lifecycle event (with a serverless-offline-watcher example), and why neither works with useInProcess.
#1531	New "Handler lifecycle" section, covering instance reuse, the termination timing, in-process shared state, and that callbackWaitsForEmptyEventLoop is ignored. terminateIdleLambdaTime now lists its default.
#1358	New Go section: without Docker, handler must point to the .go source; binary handlers and provided.* need --useDocker.

How it was checked

Each statement was checked against master, and against #1917 where that PR touches the same code (preLoadModules, LambdaFunctionPool, GoRunner); #1917 doesn't change any of the documented behaviour.

These were also run against Serverless v4.43.0:

• --debug: prints the Lambda invocation routes.
• Debugger recipe: the inspector opens in the framework process, and the handler's worker thread can be attached to over the inspector protocol. A relative preLoadModules path fails with ERR_MODULE_NOT_FOUND. NODE_OPTIONS=--inspect gets the port taken by the launcher process, so the framework process fails to start the inspector ("address already in use").
• API key example: on the local stage the fixed key is accepted and a request without a key gets 403. On prod, a random key is printed and the local key is rejected.

prettier --check README.md passes.

Closes #1358
Closes #1531
Closes #1608
Closes #1657
Closes #1659
Closes #1660
Closes #1695
Closes #1810

🤖 Generated with Claude Code

[Copilot]

Copilot review overview

🟡 Changes recommended

API-key and runtime lifecycle descriptions still conflict with the implementation.

Review effort: Balanced
Findings: 1 · 3

Open (4)

• Document cleanup timer limitation after functionsUpdated · New
• Scope pooling and termination rules to applicable runners · New
• Limit ignored-flag guarantees to Node.js in-process modes · New
• Clarify API key literals and fallback generation behavior · New

What changed in this PR

Updates serverless-offline’s README to address outdated guidance reported across eight issues.

Changes:

• Revises API-key configuration and Serverless v4 debugging instructions.
• Documents handler reuse, cleanup, and reload options.
• Explains Go source-handler and Docker requirements.

File	Description
README.md	Updates configuration, debugging, and runtime lifecycle guidance.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🔵 Needs a closer look

The documented idle-cleanup behavior depends on unmerged PR #1917, so the agreed merge order needs human confirmation.

Review effort: Balanced
Findings: None

Resolved since last review (4)

• Document cleanup timer limitation after functionsUpdated
• Clarify API key literals and fallback generation behavior
• Limit ignored-flag guarantees to Node.js in-process modes
• Scope pooling and termination rules to applicable runners

Previously missed (1)

In code that hasn't changed since last review

Avoid requiring x-api-key when authorizer supplies usageIdentifierKey

README.md:544

A request without x-api-key can still succeed when a custom authorizer returns a valid usageIdentifierKey. createAuthScheme.js forwards that value, and HttpServer.js checks it when the header is absent. Qualify the header requirement so this supported alternative is not described as returning 403.

[dherault]

Re the "previously missed" finding in the latest Copilot review (usageIdentifierKey): agreed, fixed in 0abcb07. The API keys section now says a request also passes when a Lambda authorizer returns a valid key as usageIdentifierKey (checked in HttpServer.js when the x-api-key header is absent).

[Copilot]

Copilot review overview

🔵 Needs a closer look

The documented idle-cleanup behavior depends on #1917, which remains unmerged.

Review effort: Balanced
Findings: None

Previously missed (1)

In code that hasn't changed since last review

Idle Lambda termination timeout is not a guaranteed maximum

README.md:344

Twice terminateIdleLambdaTime is not a guaranteed maximum, even after #1917. The pool waits for all idle-instance cleanups to settle before scheduling its next check, so a slow cleanup can delay termination of other idle instances. Describe one to two timeouts as approximate and note that cleanup or event-loop delays can extend it.

[dherault]

Re the "previously missed" finding in the latest Copilot review (idle termination timing): agreed, fixed in 2f1dfbe. The cleaner awaits the running cleanups before scheduling its next check, so the README now says an idle instance usually lives one to two times terminateIdleLambdaTime, and longer while a previous cleanup is still in progress.

[Copilot]

Copilot review overview

🔵 Needs a closer look

The documented cleanup behavior depends on still-unmerged PR #1917, so merge order requires verification.

Review effort: Balanced
Findings: 1

Open (1)

• Clarify termination warning for graceful and abrupt shutdown paths · New

Previously missed (1)

In code that hasn't changed since last review

Update README TOC link after renaming the heading

README.md:542

Renaming this heading leaves the table of contents at README.md:60 pointing to #token-authorizers, which no longer exists. Update that entry to [API keys](#api-keys) so the navigation link still works.

[dherault]

Re the "previously missed" finding in the latest Copilot review (TOC link): agreed, fixed in 2630c29. The table of contents now links to #api-keys, and all 39 internal links in the README resolve.

[Copilot]

Copilot review overview

🟢 Approval recommended

Only a minor documentation qualification remains, and the prerequisite fix has merged.

Review effort: Balanced
Findings: 1

Open (1)

• SIGTERM may target shell instead of Python interpreter · New

Resolved since last review (1)

• Clarify termination warning for graceful and abrupt shutdown paths

[Copilot]

Copilot review overview

🟢 Approval recommended

The documentation matches the reviewed implementation, and prior feedback is resolved.

Review effort: Balanced
Findings: None

Resolved since last review (1)

• SIGTERM may target shell instead of Python interpreter