* feat: detect token scopes at startup with graceful degradation (#188)

Add TokenScopeDetector service that calls /api/v4/personal_access_tokens/self
at startup to discover token scopes. Based on detected scopes:

- Skip GraphQL introspection when token lacks api/read_api (no 401 stack traces)
- Register only tools matching the token's permissions
- Show clean INFO messages with actionable fix URLs
- Warn when token expires within 7 days

Also adds comprehensive authentication documentation (docs/guide/authentication.md)
with PAT and OAuth walkthroughs, scope comparison table, and troubleshooting.
Links added across all installation/deployment docs.

* chore(release): 6.41.4 [skip ci]

## [6.41.4](v6.41.3...v6.41.4) (2026-01-24)

### Bug Fixes

* **auth:** use PRIVATE-TOKEN header for PAT authentication instead of Bearer ([#189](#189)) ([7799dde](7799dde)), closes [#187](#187)

* fix(auth): use enhancedFetch and UTC dates in token scope detection

- Replace global fetch with enhancedFetch in detectTokenScopes and
  detectVersionViaREST (respects timeouts, proxy, TLS settings)
- Parse expires_at as UTC date to avoid timezone off-by-one errors
- Use URL/URLSearchParams for proper encoding in getTokenCreationUrl
- Derive totalTools count dynamically from getToolScopeRequirements()
- Use jest.useFakeTimers() for deterministic expiry tests
- Test project/group token types, REST fallback, scope-gated paths

* fix(auth): deduplicate getTokenCreationUrl call, remove as-any casts

- Cache getTokenCreationUrl result in logTokenScopeInfo to avoid
  double URL construction
- Replace `as any` with proper GitLabScope[] type in test fixtures

* fix(token-scope): validate API response with Zod, remove manage_context from scope map

Replace unsafe `as` type cast on /personal_access_tokens/self response
with Zod schema validation via safeParse(). Returns null with a debug
log if the response shape doesn't match expectations.

Remove manage_context from TOOL_SCOPE_REQUIREMENTS since it manages
local session state and never calls GitLab API — it's always available.

* fix(token-scope): deep-clone scope map, preserve URL subpath, align doc counts

- getToolScopeRequirements() now returns deep clone (arrays copied too)
- getTokenCreationUrl() preserves subpath for self-hosted instances
- Documentation updated: 43 scope-gated tools, read_user=2, read_api=23
- Example log output fixed to show URL-encoded comma (%2C)

* fix(token-scope): validate scopes via z.enum, remove unreliable token type heuristic

- Replace unsafe `as GitLabScope[]` cast with z.enum validation that
  filters unknown scopes (future GitLab scopes are silently ignored)
- Derive GitLabScope type from const array via z.infer
- Remove token type detection by name prefix — token names are
  user-controlled and cannot reliably determine token type

* fix(token-scope): clarify log wording, use unknown token type, add scope filter test

- Log message now says "scope-gated tools" to clarify count excludes
  always-available tools like manage_context
- tokenType defaults to "unknown" since type cannot be reliably inferred
- Add RegistryManager unit test verifying scope-based tool filtering

* fix(test): update tokenType assertion to match unknown default

* fix(token-scope): handle schemeless URL, fix expiry-today logic, update docs

- getTokenCreationUrl() now catches URL parse errors for schemeless
  baseUrl and falls back to string concatenation
- daysUntilExpiry === 0 now logs "expires today" instead of "has expired"
- Troubleshooting docs updated to match current log format

* Update src/services/ConnectionManager.ts

Co-authored-by: Copilot <[email protected]>

* Update src/services/TokenScopeDetector.ts

Co-authored-by: Copilot <[email protected]>

* fix(test): update schemeless URL assertion for URLSearchParams encoding

---------

Co-authored-by: semantic-release-bot <[email protected]>
Co-authored-by: Copilot <[email protected]>

* fix(workitems): use two-step approach for timeEstimate on create

GitLab GraphQL API does NOT support timeTrackingWidget on WorkItemCreateInput.
This fix implements a two-step approach:
1. Create work item without timeTrackingWidget
2. Apply timeEstimate via update mutation after creation
3. Return partial success with _warning if update fails

Closes #193

* test(workitems): add test for empty workItem update response

Test scenario where timeEstimate update returns no workItem
but also no errors, verifying partial success with _warning

## [6.42.0](v6.41.4...v6.42.0) (2026-01-25)

### Features

* Token scope detection at startup with graceful degradation ([#190](#190)) ([28bab03](28bab03)), closes [#188](#188)

### Bug Fixes

* **workitems:** use two-step approach for timeEstimate on create ([#195](#195)) ([98abf4e](98abf4e)), closes [#193](#193)