linkedin-apply-assistant 0.1.1

package/docs/commands.md

@@ -0,0 +1,176 @@
+# Command Reference
+
+Use this page after installation to choose the right terminal command, inspect first-run paths, and understand where local output is written. The full install matrix remains in [Install and configuration](install-and-configuration.md).
+
+## First-Run Checklist
+
+1. Install the package from the current source/Python path documented in [Install and configuration](install-and-configuration.md).
+2. Run the read-only diagnostic:
+
+   ```powershell
+   linkedin-apply-assistant config check
+   ```
+
+3. Copy example files into your own ignored workspace when you need them:
+   - `configs/config.example.yml` for profile, documents, and path choices.
+   - `configs/qa_bank.example.yml` for truthful reusable answers.
+4. Install browser support before visible-browser workflows:
+
+   ```powershell
+   python -m playwright install chromium
+   ```
+
+5. Keep the safety boundary visible: public workflows are no-submit by default, `assist` is fill-only, and browser submission remains disabled in `apply`.
+
+## Runtime Paths
+
+`linkedin-apply-assistant config check` resolves these path categories without creating files or directories:
+
+| Path category | Purpose |
+|---|---|
+| Config file | Optional YAML config selected by `--config` or the workspace default. |
+| Q&A bank | Optional YAML answers selected by `--qa-bank` or the workspace default. |
+| Browser profile | Local visible-browser profile directory used by browser workflows. |
+| Output directory | Local command output directory. |
+| Reports directory | Local JSON report directory under the output directory. |
+| Data directory | Local assistant data such as pending questions. |
+| Cache directory | Local cache data for workflows that need it. |
+
+Use `--workspace` to keep those paths under one local directory:
+
+```powershell
+linkedin-apply-assistant --workspace .\local-workspace config check
+```
+
+Bash/macOS/Linux:
+
+```bash
+linkedin-apply-assistant --workspace ./local-workspace config check
+```
+
+## config check
+
+Run diagnostics before browser workflows or after changing path flags:
+
+```powershell
+linkedin-apply-assistant config check
+```
+
+Expected output:
+
+- `ok`, `missing`, or `warning` for each path category.
+- The resolved config file, Q&A bank, browser profile, output directory, reports directory, data directory, and cache directory.
+- Setup guidance for missing config and missing Q&A bank.
+
+This command is read-only. It does not create config files, Q&A bank files, browser profiles, output directories, reports directories, data directories, or cache directories.
+
+Try: linkedin-apply-assistant config check
+
+## search
+
+`search` collects candidate job context and writes local reports without submitting applications.
+
+```powershell
+linkedin-apply-assistant search --query "python" --location "Remote" --limit 5
+```
+
+Use an existing LinkedIn search URL when you already have one:
+
+```powershell
+linkedin-apply-assistant search --search-url "https://www.linkedin.com/jobs/search/" --limit 10 --verbose
+```
+
+Notes:
+
+- Visible browser search needs Playwright Chromium: `python -m playwright install chromium`.
+- `--limit 0` remains browser-free and can write an empty search report.
+- Reports are written under the resolved reports directory.
+- Public workflows are no-submit by default.
+
+## assist
+
+`assist` opens a visible-browser session where you drive the browser and the assistant fills detected forms. It is fill-only.
+
+```powershell
+linkedin-apply-assistant assist --mode on-demand
+```
+
+Use an explicit workspace and browser profile when you want all local state grouped:
+
+```powershell
+linkedin-apply-assistant assist --workspace .\local-workspace --browser-profile .\local-workspace\browser-profile --verbose
+```
+
+Notes:
+
+- Install browser support first: `python -m playwright install chromium`.
+- Use a truthful Q&A bank based on `configs/qa_bank.example.yml`.
+- Missing answers should pause filling or be captured as pending questions for review.
+- Reports are written under the resolved reports directory.
+- Browser submission remains disabled.
+
+## apply
+
+`apply` prepares local audit output. Browser submission remains disabled in this package boundary.
+
+```powershell
+linkedin-apply-assistant apply --input candidates.json --limit 3
+```
+
+Use verbose mode to see resolved report paths:
+
+```powershell
+linkedin-apply-assistant apply --workspace .\local-workspace --input candidates.json --verbose
+```
+
+Notes:
+
+- Current behavior is prepare-only.
+- `--confirm-submit` is recorded as a guarded future signal, but browser submission remains disabled.
+- Reports are written under the resolved reports directory.
+- Do not use the package for mass applications or unattended apply sessions.
+
+## dry-run
+
+`dry-run` validates local job JSON input. It is browser-free, does not require Playwright, does not require config, and does not require a browser profile.
+
+```powershell
+linkedin-apply-assistant dry-run --input examples\dry_run_input.example.json
+```
+
+Bash/macOS/Linux:
+
+```bash
+linkedin-apply-assistant dry-run --input examples/dry_run_input.example.json
+```
+
+Use this command to check JSON shape before browser workflows.
+
+## report
+
+`report` reads an existing local report JSON file and prints a concise summary. It is browser-free, does not require Playwright, does not require config, and does not require a browser profile.
+
+```powershell
+linkedin-apply-assistant report examples\reports\apply-audit.example.json
+```
+
+Bash/macOS/Linux:
+
+```bash
+linkedin-apply-assistant report examples/reports/apply-audit.example.json
+```
+
+Use this command for local report review without opening a browser.
+
+## Troubleshooting Pointers
+
+| Symptom | Next step |
+|---|---|
+| Missing config | Run `linkedin-apply-assistant config check`, then copy and edit `configs/config.example.yml` if you need config. |
+| Missing Q&A bank | Copy `configs/qa_bank.example.yml`, answer truthfully, and pass it with `--qa-bank` or a workspace default. |
+| Invalid JSON input | Re-run `dry-run` after checking the `--input` path and JSON format. |
+| Missing Playwright or Chromium | Run `python -m playwright install chromium`. |
+| Browser profile issue | Run `config check`, inspect the browser profile path, or choose another profile with `--browser-profile <path>`. |
+| Unsure which command to use | Start with `linkedin-apply-assistant --help` and `linkedin-apply-assistant config check`. |
+
+More details are in [Troubleshooting](troubleshooting.md).

package/docs/install-and-configuration.md

@@ -0,0 +1,265 @@
+# Install and Configuration
+
+This package runs locally. You install the Python package, choose a local workspace, and keep personal runtime files out of version control.
+
+This file is the canonical install matrix. The README keeps only a short quick start.
+
+Current package metadata version: `0.1.1`.
+
+The npm launcher and PowerShell installer are the current quick-install paths.
+PyPI remains a future package channel. The package-channel decision, approval
+gates, and `v0.1.0` no-backfill policy are documented in the
+[registry publication strategy](registry-publication-strategy.md).
+
+## Prerequisites
+
+- Python 3.11 or newer.
+- A shell such as PowerShell, Bash, zsh, or another POSIX-like shell.
+- Node.js/npm for the npm global launcher path.
+- PowerShell 5.1+ or PowerShell 7+ for the Windows installer path.
+- Playwright Chromium only for visible-browser workflows.
+
+Browser-free commands such as `dry-run` and `report` do not need a Playwright browser install. Commands that open a visible browser, such as `search`, `assist`, and browser-dependent `apply` preparation, need Chromium:
+
+```powershell
+python -m playwright install chromium
+```
+
+## NPM Global Launcher
+
+The npm package provides the `linkedin-apply-assistant` command as a Node
+launcher. It delegates to the Python CLI and still needs Python 3.11+ plus the
+Python dependencies.
+
+```powershell
+npm install -g linkedin-apply-assistant
+linkedin-apply-assistant --help
+```
+
+If the launcher reports that the Python package is not importable, install the
+bundled Python package from the global npm package directory:
+
+```powershell
+$pkg = Join-Path (npm root -g) 'linkedin-apply-assistant'
+py -3 -m pip install $pkg
+linkedin-apply-assistant --help
+```
+
+## PowerShell Installer
+
+The PowerShell installer downloads the public GitHub source archive, creates a
+local virtual environment, installs the Python package, and writes
+`linkedin-apply-assistant.ps1` plus `.cmd` shims under the install directory. It
+does not require admin rights.
+
+```powershell
+$script = Join-Path $env:TEMP 'install-linkedin-apply-assistant.ps1'
+Invoke-WebRequest -UseBasicParsing https://raw.githubusercontent.com/MohammedGhazal09/linkedin-apply-assistant/main/install.ps1 -OutFile $script
+powershell -ExecutionPolicy Bypass -File $script
+```
+
+Optional visible-browser setup during install:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File $script -InstallBrowser
+```
+
+## Current Source Checkout
+
+Run these commands from the package root, not from a broader parent repository root.
+
+Install the package for local development:
+
+```powershell
+python -m pip install -e ".[dev]"
+```
+
+Check the console command:
+
+```powershell
+linkedin-apply-assistant --help
+linkedin-apply-assistant config check
+```
+
+After installation, use the [command reference](commands.md) for first-run diagnostics, public command examples, output paths, reports, and browser-profile guidance.
+
+If you are working directly from source and need a module fallback, set `PYTHONPATH` to the local `src` directory.
+
+PowerShell:
+
+```powershell
+$env:PYTHONPATH=(Resolve-Path 'src').Path
+python -m linkedin_apply_assistant.cli --help
+```
+
+Bash/macOS/Linux:
+
+```bash
+PYTHONPATH="$(pwd)/src" python -m linkedin_apply_assistant.cli --help
+```
+
+## Public Source Download
+
+The canonical public source repository is:
+
+```text
+https://github.com/MohammedGhazal09/linkedin-apply-assistant
+```
+
+Git clone:
+
+```bash
+git clone https://github.com/MohammedGhazal09/linkedin-apply-assistant.git
+cd linkedin-apply-assistant
+python -m pip install -e ".[dev]"
+linkedin-apply-assistant --help
+```
+
+ZIP/tarball archive shape:
+
+1. Download the ZIP/tarball archive from the public repository source archive links.
+2. Extract it.
+3. Open a shell in the extracted package root.
+4. Install and verify:
+
+```bash
+python -m pip install -e ".[dev]"
+linkedin-apply-assistant --help
+```
+
+## Python Install Paths
+
+For a local package root checkout:
+
+```powershell
+python -m pip install .
+linkedin-apply-assistant --help
+```
+
+For editable development with test and release tooling:
+
+```powershell
+python -m pip install -e ".[dev]"
+linkedin-apply-assistant --help
+```
+
+For an isolated application install with pipx from a local package root:
+
+```powershell
+pipx install .
+linkedin-apply-assistant --help
+```
+
+After a later approved PyPI release, the future pipx command shape will use the package name:
+
+```powershell
+pipx install linkedin-apply-assistant
+```
+
+Until that release exists, use the local package-root commands above.
+
+## npm Launcher Path
+
+The package-local npm path is a thin launcher for users who want an npm-installed command. It delegates to the Python CLI and does not install Python dependencies for you.
+
+From the package root, test the launcher locally after making the Python package importable.
+
+PowerShell:
+
+```powershell
+$env:PYTHONPATH=(Resolve-Path 'src').Path
+node .\bin\linkedin-apply-assistant.mjs --help
+```
+
+Bash/macOS/Linux:
+
+```bash
+PYTHONPATH="$(pwd)/src" node ./bin/linkedin-apply-assistant.mjs --help
+```
+
+Local package-shape validation uses npm packaging dry runs rather than registry publication:
+
+```powershell
+npm pack --dry-run --json
+```
+
+The global npm command shape is:
+
+```powershell
+npm install -g linkedin-apply-assistant
+linkedin-apply-assistant --help
+```
+
+If imports are missing after the npm install, use the bundled package-root pip
+command from the NPM Global Launcher section above.
+
+## Browser-Free Commands
+
+`dry-run` validates local input without opening a browser:
+
+```powershell
+linkedin-apply-assistant dry-run --input examples\dry_run_input.example.json
+```
+
+`report` reads a local report JSON file and prints a summary without opening a browser:
+
+```powershell
+linkedin-apply-assistant report examples\reports\apply-audit.example.json
+```
+
+## Visible-Browser Workflows
+
+Visible-browser workflows are user-controlled and no-submit by default. Use the Playwright Chromium prerequisite command above before opening them.
+
+Then review each command's help:
+
+```powershell
+linkedin-apply-assistant config check
+linkedin-apply-assistant search --help
+linkedin-apply-assistant assist --help
+linkedin-apply-assistant apply --help
+```
+
+`search` collects candidate job context and writes local reports. `assist` opens a visible-browser fill-only session. `apply` prepares approval-gated audit output; browser submission remains disabled today.
+
+## Workspace
+
+Use `--workspace` to point the assistant at a local directory for config, data, visible-browser profile, outputs, and reports:
+
+```powershell
+linkedin-apply-assistant --workspace .\local-workspace dry-run --input examples\dry_run_input.example.json
+```
+
+The package `.gitignore` excludes local runtime directories such as `data/`, `output/`, `reports/`, `browser-profile/`, and local config files. Keep real answers and browser state local.
+
+## Config
+
+Start from [../configs/config.example.yml](../configs/config.example.yml). Copy it to your own ignored workspace before adding real local paths.
+
+Use `--config` to choose the file:
+
+```powershell
+linkedin-apply-assistant --config .\local-workspace\config.yml dry-run --input examples\dry_run_input.example.json
+```
+
+Do not put credentials in the package config. Browser login state belongs in your local visible-browser profile, and the profile directory should stay ignored.
+
+## Q&A Bank
+
+Start from [../configs/qa_bank.example.yml](../configs/qa_bank.example.yml). The Q&A bank should contain truthful, reusable answers only. Unknown required questions should stop the workflow until the user supplies an answer.
+
+Use `--qa-bank` to choose a local file:
+
+```powershell
+linkedin-apply-assistant --qa-bank .\local-workspace\qa_bank.yml dry-run --input examples\dry_run_input.example.json
+```
+
+## Output Directory
+
+Use `--output-dir` when you want command output somewhere specific:
+
+```powershell
+linkedin-apply-assistant --output-dir .\local-workspace\outputs dry-run --input examples\dry_run_input.example.json
+```
+
+Generated output is local audit material. Do not publish it unless you have reviewed and sanitized it.

package/docs/registry-publication-strategy.md

@@ -0,0 +1,169 @@
+# Registry Publication Strategy
+
+Status: registry and installer policy. This document does not by itself publish
+a package, reserve a package name, configure a trusted publisher, create a
+registry token, log in to a registry, create a tag, upload a GitHub Release
+asset, or grant publish-capable workflow permissions.
+
+The first GitHub source release, `v0.1.0`, remains source-only and is not a
+registry backfill candidate. The npm launcher release starts at `0.1.1`; PyPI
+and TestPyPI remain future channels.
+
+## Current Boundary
+
+- Current package metadata version: `0.1.1`.
+- Current install path: npm global launcher, PowerShell installer, source
+  checkout, local Python install, local editable install, and local npm launcher
+  dry-run validation.
+- Current public channel: GitHub repository source checkout and GitHub source
+  release archives; npm launcher package for `0.1.1` after the approved npm
+  publish step verifies successfully.
+- Not current: PyPI package, TestPyPI package, GitHub Packages package, PyPI
+  trusted-publisher setup, npm trusted-publisher setup, registry automation,
+  release asset uploads, artifact attestations, provenance, or signing.
+
+PyPI registry install commands remain future commands until a later phase
+explicitly approves the target registry, version, repository, workflow or manual
+action, and exact mutation.
+
+## Channel Matrix
+
+| Channel | Current status | Future status | Rationale | Prerequisites | Publish trigger | Verification | Rollback or remediation |
+|---|---|---|---|---|---|---|---|
+| GitHub Releases | Current source-only channel for `v0.1.0`. No wheel, sdist, npm tarball, or other release asset is attached. | Keep as the source-of-truth release record. Future assets require explicit approval. | Users can inspect and install from source without introducing registry auth or package-name ownership. | Clean local verification, changelog, release checklist, source manifest, approved tag or release mutation. | Explicit GitHub Release approval naming repo, tag, target commit, release state, and assets, if any. | `gh release view`, `gh release list`, source archive inspection, release manifest verification. | Remove mistaken assets from the release, correct the release notes, or delete a draft. Source tags need separate explicit remediation because asset removal does not undo a tag. |
+| PyPI | Not published and not reserved. | Primary future Python registry for direct package publication. | The project is a Python CLI with Playwright-driven browser automation, so PyPI is the natural long-term install path. | Maintainer or maintainer-controlled organization ownership, account 2FA where supported, PyPI Trusted Publishing with GitHub Actions OIDC, protected `pypi` environment, clean build and metadata gates. | Explicit PyPI approval naming repository, version, PyPI project, workflow or manual action, and exact upload mutation. | Read-only JSON API check, `python -m build`, `twine check dist/*`, local wheel install smoke, release scan, manifest verification. | Prefer yanking a broken release where appropriate. Deletion is disruptive and permanent; never rely on deleting and reusing the same version. |
+| TestPyPI | Not published and not reserved. | Required preflight for the first registry release and for publish-workflow changes. Routine patch preflights can become optional only after a proven release cycle. | It exercises package metadata, artifacts, and installer behavior before the real PyPI release. | Same artifact gates as PyPI, protected `testpypi` environment, explicit preflight approval, no production token. | Explicit TestPyPI approval naming repository, version, TestPyPI project, workflow or manual action, and exact upload mutation. | TestPyPI JSON API check, metadata validation, test-index install smoke, package contents review. | Clean up mistaken TestPyPI releases where possible and move forward with a new version if needed. Do not treat TestPyPI cleanup as production rollback proof. |
+| npm | Public thin-launcher channel for `0.1.1`. | Keep as the JavaScript ecosystem convenience launcher; use PyPI later for direct Python package installs. | npm provides a familiar global command on systems that already have Node.js, but the launcher delegates to the Python CLI and cannot install Python itself. | Maintainer or maintainer-controlled ownership, account 2FA where supported, first-publish token bootstrap if trusted publishing cannot create the package, exact package contents review. | Explicit npm approval naming repository, version, npm package, workflow or manual action, and exact registry mutation. | `npm pack --dry-run --json`, package contents inspection, no lifecycle install/publish scripts, npm read-only registry check after publication. | Prefer deprecation for bad packages when unpublish criteria are not met. A used npm `package@version` cannot be reused, even after unpublish. |
+| PowerShell installer | Current GitHub-hosted installer script at `install.ps1`. | Keep as the no-admin Windows convenience path for users who prefer a single script. | It can create a local virtual environment, install dependencies from the public source archive, create command shims, and optionally install Chromium. | Public GitHub source archive availability, Python 3.11+, script syntax validation, no `Invoke-Expression` pipe-install pattern, and local install smoke. | Push the verified installer to the public repository; no registry mutation is required. | PowerShell parser check, temp-directory install smoke, command shim help smoke, and docs link checks. | Fix forward in `main`; users can reinstall from the corrected script or pin `-Ref` to a known tag. |
+| GitHub Packages | Not used. | Deferred. | It adds `packages: write` and authenticated consumption friction without improving the primary Python install path. | A future reason to publish a package to GitHub Packages, explicit package type, permission model, and install documentation. | Separate approval naming package type, repository, version, and exact mutation. | GitHub Packages read-only checks and package permission review. | Delete or deprecate only according to the package type's GitHub Packages support. This is not a substitute for PyPI/npm remediation. |
+
+## Package Names
+
+The target package name for PyPI, TestPyPI, and npm publication is
+`linkedin-apply-assistant`. The current npm launcher version is `0.1.1`.
+
+If the unscoped npm name becomes unavailable or ownership changes later, the
+fallback is a future scoped npm package under a maintainer-controlled scope.
+
+## Version Sequencing
+
+- `v0.1.0` stays a GitHub source-only release.
+- No registry should backfill `0.1.0`.
+- The first registry release must use a later explicitly approved package version.
+- The npm launcher release uses `0.1.1` because it changes distribution
+  metadata, includes the Python source in the npm tarball, and adds the
+  PowerShell installer without changing the browser workflow contract.
+- If user-visible behavior changes before registry publication, the default
+  future version example is `0.2.0`.
+- Future behavior changes remain SemVer decisions at the publish phase.
+
+## Ownership and Authentication
+
+Future registry publication must use maintainer-owned or maintainer-controlled
+organization accounts.
+
+Required future controls:
+
+- Account 2FA where the registry supports it.
+- PyPI Trusted Publishing with GitHub Actions OIDC for PyPI/TestPyPI.
+- npm trusted publishing or equivalent OIDC flow where supported after the first
+  package bootstrap. A brand-new npm package may need a short-lived granular
+  token for the first publish before trusted publishing can be linked.
+- Protected GitHub environments such as `testpypi`, `pypi`, and `npm`.
+- A tightly scoped future release workflow identity, commonly `release.yml`, but
+- no release workflow is added by this document.
+- No shared long-lived registry tokens.
+- No publish credentials in repository files, examples, local configs, or
+  package metadata.
+
+Future OIDC and attestation work may require permissions such as
+`id-token: write`, `attestations: write`, or `packages: write`. Phase 29 does not grant those permissions.
+
+## Future Publish Gates
+
+Every future registry publication approval must include fresh evidence for the
+target version:
+
+- Python build: `python -m build`.
+- Python metadata validation: `twine check dist/*`.
+- Local wheel install smoke from a temporary output directory.
+- npm launcher package dry run: `npm pack --dry-run --json`.
+- Package contents inspection for source release and npm package surfaces.
+- PowerShell installer parser check and temp-directory install smoke.
+- Release manifest check: `python scripts\release.py manifest --check`.
+- Release verification: `python scripts\release.py verify`.
+- Secret scan or release scan with gitleaks or the package release scanner.
+- Read-only npm, PyPI, and TestPyPI registry version or absence checks.
+- GitHub Release read-only checks when source tags or release assets are in
+  scope.
+
+Live registry checks stay out of default pytest and CI. They are verification
+commands for the human-approved release step.
+
+## Approval Templates
+
+Use these templates verbatim before any future registry or release mutation.
+
+### TestPyPI Preflight
+
+- Repository: `MohammedGhazal09/linkedin-apply-assistant`
+- Version: `<version>`
+- Channel: TestPyPI
+- Workflow or manual action: `<workflow filename or manual command owner>`
+- Exact mutation: upload the verified sdist and wheel for `<version>` to
+  TestPyPI only.
+
+### PyPI Release
+
+- Repository: `MohammedGhazal09/linkedin-apply-assistant`
+- Version: `<version>`
+- Channel: PyPI
+- Workflow or manual action: `<workflow filename or manual command owner>`
+- Exact mutation: upload the verified sdist and wheel for `<version>` to PyPI.
+
+### npm Launcher Release
+
+- Repository: `MohammedGhazal09/linkedin-apply-assistant`
+- Version: `0.1.1`
+- Channel: npm
+- Workflow or manual action: `<workflow filename or manual command owner>`
+- Exact mutation: publish the verified npm launcher package for `<version>` to
+  the npm public registry.
+
+### PowerShell Installer Update
+
+- Repository: `MohammedGhazal09/linkedin-apply-assistant`
+- Version or ref: `<version-or-ref>`
+- Channel: GitHub raw source installer
+- Workflow or manual action: `<workflow filename or manual command owner>`
+- Exact mutation: push the verified `install.ps1` installer script to the
+  public repository.
+
+### GitHub Release Asset Work
+
+- Repository: `MohammedGhazal09/linkedin-apply-assistant`
+- Version or tag: `<version-or-tag>`
+- Channel: GitHub Releases
+- Workflow or manual action: `<workflow filename or manual command owner>`
+- Exact mutation: upload, replace, or remove the named release asset(s) for
+  `<version-or-tag>`.
+
+## Rollback and Remediation Notes
+
+- PyPI: prefer yanking for broken releases where appropriate. Deletion is
+  disruptive and should not be treated as a normal rollback path.
+- TestPyPI: cleanup is acceptable for preflight mistakes, but it does not prove
+  production rollback.
+- npm: unpublish is limited and irreversible in important ways; deprecation is often the safer remediation path. A used package version cannot be reused.
+- GitHub Releases: removing a release asset does not remove source archives,
+  tags, or downstream copies. Tag remediation requires a separate explicit
+  approval.
+
+Do not add executable rollback scripts for registry actions until a future phase
+has a concrete approved publication mechanism.
+
+## Related Docs
+
+- [Install and configuration](install-and-configuration.md)
+- [CI and release policy](ci-and-release-policy.md)
+- [Release checklist](../RELEASE_CHECKLIST.md)

package/docs/reports.md

@@ -0,0 +1,35 @@
+# Report Review
+
+`report` reads a local JSON report and prints a concise summary for review.
+
+## Review a Report
+
+```powershell
+linkedin-apply-assistant report examples\reports\search-report.example.json
+```
+
+Synthetic examples:
+
+- [../examples/reports/search-report.example.json](../examples/reports/search-report.example.json)
+- [../examples/reports/apply-audit.example.json](../examples/reports/apply-audit.example.json)
+
+## Report Boundary
+
+Reports are local audit material. They can contain company names, role names, status counts, blockers, and decisions. They should not contain credentials, cookies, tokens, raw browser state, raw HTML, screenshots, full private URLs, private documents, or generated local reports copied from a real run.
+
+Use examples to understand shape only. Replace or redact sensitive data before sharing any report outside your machine.
+
+## Related Commands
+
+Generate browser-free dry-run output:
+
+```powershell
+linkedin-apply-assistant dry-run --input examples\dry_run_input.example.json
+```
+
+Prepare local apply audit output without browser submission:
+
+```powershell
+linkedin-apply-assistant apply --input examples\dry_run_input.example.json --limit 1
+```
+

package/docs/search.md

@@ -0,0 +1,39 @@
+# Search-Only Workflow
+
+`search` collects candidate job context and writes local report output without submitting applications.
+
+## Basic Search
+
+```powershell
+linkedin-apply-assistant search --query "applied ai engineer" --location "Remote" --limit 10
+```
+
+Use `--search-url` when you already have a LinkedIn jobs search URL:
+
+```powershell
+linkedin-apply-assistant search --search-url "https://www.linkedin.com/jobs/search/" --limit 5
+```
+
+## Shared Options
+
+`search` accepts the shared package flags:
+
+- `--workspace`
+- `--config`
+- `--qa-bank`
+- `--browser-profile`
+- `--output-dir`
+- `--verbose`
+
+Example:
+
+```powershell
+linkedin-apply-assistant --workspace .\local-workspace search --query "automation engineer" --location "Remote" --limit 5 --verbose
+```
+
+## Output
+
+Search output is local audit material. Review it before sharing. Do not publish full private URLs, browser state, generated local reports, or live job history.
+
+For report review, see [reports.md](reports.md).
+