docs: consolidate and cross-link documentation - #5
Merged
Conversation
- README: add Documentation cross-reference table linking USER_GUIDE, COMMAND_REFERENCE, ERROR_REFERENCE, PERFORMANCE, ARCHITECTURE, CONTRIBUTING, DISCLAIMER - COMMAND_REFERENCE: add library and status rows to Native LR Commands table (parity with $script:LR_NativeCmds) - USER_GUIDE: drop obsolete top-level 'mode' config field from example and clarify -Mode CLI behaviour - ARCHITECTURE: drop 'Framework Bugs Found & Fixed' dev-history section and stale dated test-results table; clarify -Mode CLI behaviour - DISCLAIMER: refresh last-updated date
… (25 total) The 'help commands' block advertised '23 total' but listed 26 entries (25 native + 'config' which is a shell built-in, not a native LR cmd). Main help screen already says '25 total' and matches the authoritative $script:LR_NativeCmds array. Sync the two screens.
- .github/dependabot.yml: weekly github-actions version bumps (keeps actions/checkout@v4 etc. patched automatically) - SECURITY.md: private vulnerability reporting channel and scope, referenced from GitHub's Security tab for the repo
- README: add CI/license/PS-version/platform badges - PSScriptAnalyzerSettings: document and suppress rules that reflect architectural choices (empty catch = intentional best-effort paths, plural nouns = collection-returning helpers, plain-text password = Entra credential-auth flow). Shell warnings drop 41 -> 8; remaining are genuine 'review unused parameter' signals worth keeping visible. - CONTRIBUTING: add local PSScriptAnalyzer install + run command, point security reports at SECURITY.md
- README + USER_GUIDE: replace 'cp' with 'Copy-Item' in quick-start examples so the command works on Windows PowerShell (cp is a pwsh alias only on non-Windows) - README: add SECURITY.md and REFERENCES.md to documentation table (REFERENCES was previously orphaned) - README: replace vague '1,100+ tests' with the real breakdown (712 offline + 301 Official + 251 Internal + stress driver) - tests/README.md: drop stale 2026-04-03 results table, align test counts with actual Pester It-block counts (712/301/251), retitle CI line to match the truth - ARCHITECTURE.md: 736 -> 712 for offline Pester test count
Content-accuracy fixes after auditing docs against source of truth: - Rate limiter: actual error strings are "[RateLimit] API rate limit reached...", "[Conflict] Another command is running...", "[Retry] Waiting Ns...". ActiveRequest backoff is fixed 10s then 15s (not exponential), up to 12 retries. 502/503/504 uses exponential backoff (2^attempt * 3s, capped at 60s), up to 5 retries. - Library download: works in both modes. Internal is direct; Official issues getfile against the endpoint's local cache path, subject to up-to-10-minute sync delay. Removed the "Internal only" claim. - remediate/undo: literal "file" token is required -- documented. - commandTimeoutSeconds default: code ships with 0 (= server decides, up to 1800s). The example config ships with 300. Per-command overrides are independent. - ARCHITECTURE rate-limit table: ActiveRequest is fixed backoff, not exponential. - Auth-refresh table: method 1 only auto-refreshes when a TOTP secret was supplied (push/SMS MFA cannot silently re-auth); method 5 (direct sccauth) cannot refresh cookies supplied by the user. - SECURITY.md: document credential-handling trade-offs (method 1 retains password + TOTP secret in-memory for silent re-auth; PSReadLine history disabled; no secrets on CLI).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
libraryandstatusrows to Native LR Commands table (matches$script:LR_NativeCmds, 25 total)modeconfig field from example, clarify-ModeCLI behaviourTest plan