linkfetch 0.1.0__tar.gz

linkfetch-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,63 @@
+name: Release
+
+# Push a tag like v0.1.1 to publish that version to PyPI. Publishing uses
+# PyPI trusted publishing (OpenID Connect): no API token is stored anywhere.
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.13"
+      - name: Tag matches the package version
+        run: |
+          version=$(uv version --short)
+          if [ "v$version" != "$GITHUB_REF_NAME" ]; then
+            echo "Tag $GITHUB_REF_NAME does not match pyproject version $version" >&2
+            exit 1
+          fi
+      - run: uv sync --extra dev --locked
+      - run: uv run pytest -q
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/linkfetch/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Create the GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release create "$GITHUB_REF_NAME" dist/* --repo "$GITHUB_REPOSITORY" --title "$GITHUB_REF_NAME" --generate-notes

linkfetch-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,30 @@
+name: Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Python ${{ matrix.python }} on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python: ["3.10", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python }}
+      # Tests exercise parsing and config only, so the Chromium download that
+      # `linkfetch capture` needs is skipped.
+      - run: uv sync --extra dev --locked
+      - run: uv run pytest -q
+      - name: Build the package
+        run: uv build

linkfetch-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+# data: captured HTML, emitted YAML, browser profile
+/data/
+
+# python
+__pycache__/
+*.py[cod]
+.venv/
+*.egg-info/
+.pytest_cache/
+dist/
+build/
+
+# os
+.DS_Store

linkfetch-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Prosperis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

linkfetch-0.1.0/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.5
+Name: linkfetch
+Version: 0.1.0
+Summary: Capture your own LinkedIn profile on your own computer and turn it into structured profile files
+Project-URL: Homepage, https://github.com/Prosperis/linkfetch
+Project-URL: Issues, https://github.com/Prosperis/linkfetch/issues
+Author: Prosperis
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cv,export,linkedin,playwright,profile,resume
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business
+Requires-Python: >=3.10
+Requires-Dist: lxml>=5.0
+Requires-Dist: playwright>=1.44
+Requires-Dist: pydantic>=2.6
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.7
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Requires-Dist: typer>=0.12
+Provides-Extra: browser
+Provides-Extra: dev
+Requires-Dist: pytest-mock>=3.12; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# linkfetch
+
+Capture **your own** LinkedIn profile on **your own computer** and turn it into
+structured profile files — every role, description, skill, project,
+certification and more — ready to import into
+[THRIVE](https://prosperis-thrive.vercel.app) or any tool that reads YAML.
+
+LinkedIn's official data export leaves out details the profile page shows.
+linkfetch reads the rendered pages instead, in a real browser window that you
+log into yourself.
+
+## What it does and does not do
+
+- **Runs only on your machine.** linkfetch is not a website or a service. It
+  sends your data nowhere; the files it writes stay in a folder on your
+  computer until you choose to upload them.
+- **Reads only your own profile**, in a browser you log into. It never sees
+  your password: you type it into LinkedIn's own login page.
+- **Deterministic, no AI.** Every field comes straight from the page.
+- **Open source** (MIT), so you can read exactly what it does.
+
+## Install
+
+You need Python 3.10 or newer and [uv](https://docs.astral.sh/uv/) (or
+[pipx](https://pipx.pypa.io/)).
+
+```bash
+uv tool install linkfetch        # or: pipx install linkfetch
+linkfetch doctor                 # shows where data is kept and whether Playwright and a login exist
+playwright install chromium      # one-time download of the browser linkfetch drives
+```
+
+## Use
+
+```bash
+linkfetch login                       # a browser window opens: log in to LinkedIn, then close it
+linkfetch run --vanity your-name      # capture your profile and build the files
+```
+
+`your-name` is the part after `/in/` in your profile address:
+`linkedin.com/in/your-name`.
+
+`run` visits each section of your profile (experience, education, skills, …),
+expands every "see more", saves the pages, and turns them into one YAML file
+per section plus **`linkfetch-profile.zip`**. `linkfetch` prints where they
+are.
+
+### Import into THRIVE
+
+In THRIVE, open **Tailor → Profile → Import** and choose
+`linkfetch-profile.zip`. Review each section before saving.
+
+## Where your data is kept
+
+Installed with `uv tool` or `pipx`, linkfetch keeps everything in your user
+data folder:
+
+| OS | Folder |
+|---|---|
+| Windows | `%LOCALAPPDATA%\linkfetch` |
+| macOS | `~/Library/Application Support/linkfetch` |
+| Linux | `$XDG_DATA_HOME/linkfetch` (usually `~/.local/share/linkfetch`) |
+
+Set `LINKFETCH_HOME` to use a different folder. Inside it:
+
+- `data/browser/` — the browser profile that keeps you logged in to LinkedIn.
+  Treat it like a password; delete it to log out.
+- `data/captures/` — the saved profile pages.
+- `data/output/` — the YAML files and `linkfetch-profile.zip`.
+
+Delete the folder to remove everything linkfetch stored.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `linkfetch doctor` | Show the data folders and check Playwright and your login |
+| `linkfetch login` | Open a browser window to log in to LinkedIn once |
+| `linkfetch capture --vanity <you>` | Save your profile pages (needs the browser) |
+| `linkfetch parse` | Turn saved pages into YAML and the ZIP (no browser; re-runnable) |
+| `linkfetch run --vanity <you>` | `capture` then `parse` |
+
+Use `--section experience --section skills` to limit a run to some sections,
+and `parse --no-zip` to skip the ZIP.
+
+## Output
+
+One file per section, each a list under a top-level key:
+`basics.yaml`, `experiences.yaml`, `education.yaml`, `skills.yaml`,
+`projects.yaml`, `certifications.yaml`, `awards.yaml`, `languages.yaml`,
+`courses.yaml`, `patents.yaml`, `recommendations.yaml`, `volunteering.yaml`,
+plus `honors.yaml` (a richer copy of awards, not included in the ZIP).
+Experiences keep their full description as a summary plus bullets, and roles
+at the same company stay grouped.
+
+## How it works
+
+1. **Capture** (needs the browser, runs rarely): a persistent Chromium profile
+   you logged into visits each section's details page
+   (`/in/<you>/details/experience/`, …), expands collapsed content, and saves
+   the rendered HTML.
+2. **Parse** (pure, offline): reads the saved HTML with `lxml` and writes YAML.
+   If LinkedIn changes its pages, a parser fix plus `linkfetch parse` is enough
+   — no need to capture again.
+
+## Development
+
+```bash
+git clone https://github.com/Prosperis/linkfetch
+cd linkfetch
+uv venv && uv pip install -e ".[dev]"
+playwright install chromium
+uv run pytest
+```
+
+A checkout keeps its data in `data/` next to `config.toml`, which also holds
+browser settings (headless mode, timeouts, scroll pacing). Test fixtures are
+anonymized excerpts of LinkedIn's page structure.
+
+## Releasing
+
+Bump `version` in `pyproject.toml`, commit, then push a matching tag:
+
+```bash
+git tag v0.1.1 && git push origin v0.1.1
+```
+
+The Release workflow tests, builds and publishes to PyPI through trusted
+publishing (no stored token), then creates the GitHub release.
+
+## Legal note
+
+LinkedIn's User Agreement restricts automated access. linkfetch is meant for
+**personal use on your own profile**: it uses a browser you logged into, moves
+at a human pace, reads only your own data and stores nothing remotely. Use it
+on your own account and at your own discretion.
+
+## License
+
+[MIT](LICENSE) © Prosperis

linkfetch-0.1.0/README.md

@@ -0,0 +1,140 @@
+# linkfetch
+
+Capture **your own** LinkedIn profile on **your own computer** and turn it into
+structured profile files — every role, description, skill, project,
+certification and more — ready to import into
+[THRIVE](https://prosperis-thrive.vercel.app) or any tool that reads YAML.
+
+LinkedIn's official data export leaves out details the profile page shows.
+linkfetch reads the rendered pages instead, in a real browser window that you
+log into yourself.
+
+## What it does and does not do
+
+- **Runs only on your machine.** linkfetch is not a website or a service. It
+  sends your data nowhere; the files it writes stay in a folder on your
+  computer until you choose to upload them.
+- **Reads only your own profile**, in a browser you log into. It never sees
+  your password: you type it into LinkedIn's own login page.
+- **Deterministic, no AI.** Every field comes straight from the page.
+- **Open source** (MIT), so you can read exactly what it does.
+
+## Install
+
+You need Python 3.10 or newer and [uv](https://docs.astral.sh/uv/) (or
+[pipx](https://pipx.pypa.io/)).
+
+```bash
+uv tool install linkfetch        # or: pipx install linkfetch
+linkfetch doctor                 # shows where data is kept and whether Playwright and a login exist
+playwright install chromium      # one-time download of the browser linkfetch drives
+```
+
+## Use
+
+```bash
+linkfetch login                       # a browser window opens: log in to LinkedIn, then close it
+linkfetch run --vanity your-name      # capture your profile and build the files
+```
+
+`your-name` is the part after `/in/` in your profile address:
+`linkedin.com/in/your-name`.
+
+`run` visits each section of your profile (experience, education, skills, …),
+expands every "see more", saves the pages, and turns them into one YAML file
+per section plus **`linkfetch-profile.zip`**. `linkfetch` prints where they
+are.
+
+### Import into THRIVE
+
+In THRIVE, open **Tailor → Profile → Import** and choose
+`linkfetch-profile.zip`. Review each section before saving.
+
+## Where your data is kept
+
+Installed with `uv tool` or `pipx`, linkfetch keeps everything in your user
+data folder:
+
+| OS | Folder |
+|---|---|
+| Windows | `%LOCALAPPDATA%\linkfetch` |
+| macOS | `~/Library/Application Support/linkfetch` |
+| Linux | `$XDG_DATA_HOME/linkfetch` (usually `~/.local/share/linkfetch`) |
+
+Set `LINKFETCH_HOME` to use a different folder. Inside it:
+
+- `data/browser/` — the browser profile that keeps you logged in to LinkedIn.
+  Treat it like a password; delete it to log out.
+- `data/captures/` — the saved profile pages.
+- `data/output/` — the YAML files and `linkfetch-profile.zip`.
+
+Delete the folder to remove everything linkfetch stored.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `linkfetch doctor` | Show the data folders and check Playwright and your login |
+| `linkfetch login` | Open a browser window to log in to LinkedIn once |
+| `linkfetch capture --vanity <you>` | Save your profile pages (needs the browser) |
+| `linkfetch parse` | Turn saved pages into YAML and the ZIP (no browser; re-runnable) |
+| `linkfetch run --vanity <you>` | `capture` then `parse` |
+
+Use `--section experience --section skills` to limit a run to some sections,
+and `parse --no-zip` to skip the ZIP.
+
+## Output
+
+One file per section, each a list under a top-level key:
+`basics.yaml`, `experiences.yaml`, `education.yaml`, `skills.yaml`,
+`projects.yaml`, `certifications.yaml`, `awards.yaml`, `languages.yaml`,
+`courses.yaml`, `patents.yaml`, `recommendations.yaml`, `volunteering.yaml`,
+plus `honors.yaml` (a richer copy of awards, not included in the ZIP).
+Experiences keep their full description as a summary plus bullets, and roles
+at the same company stay grouped.
+
+## How it works
+
+1. **Capture** (needs the browser, runs rarely): a persistent Chromium profile
+   you logged into visits each section's details page
+   (`/in/<you>/details/experience/`, …), expands collapsed content, and saves
+   the rendered HTML.
+2. **Parse** (pure, offline): reads the saved HTML with `lxml` and writes YAML.
+   If LinkedIn changes its pages, a parser fix plus `linkfetch parse` is enough
+   — no need to capture again.
+
+## Development
+
+```bash
+git clone https://github.com/Prosperis/linkfetch
+cd linkfetch
+uv venv && uv pip install -e ".[dev]"
+playwright install chromium
+uv run pytest
+```
+
+A checkout keeps its data in `data/` next to `config.toml`, which also holds
+browser settings (headless mode, timeouts, scroll pacing). Test fixtures are
+anonymized excerpts of LinkedIn's page structure.
+
+## Releasing
+
+Bump `version` in `pyproject.toml`, commit, then push a matching tag:
+
+```bash
+git tag v0.1.1 && git push origin v0.1.1
+```
+
+The Release workflow tests, builds and publishes to PyPI through trusted
+publishing (no stored token), then creates the GitHub release.
+
+## Legal note
+
+LinkedIn's User Agreement restricts automated access. linkfetch is meant for
+**personal use on your own profile**: it uses a browser you logged into, moves
+at a human pace, reads only your own data and stores nothing remotely. Use it
+on your own account and at your own discretion.
+
+## License
+
+[MIT](LICENSE) © Prosperis

linkfetch-0.1.0/config.toml

@@ -0,0 +1,16 @@
+# linkfetch configuration.
+# Paths are relative to this file's directory unless absolute.
+
+[paths]
+captures = "data/captures"   # rendered HTML saved by `linkfetch capture`
+output = "data/output"       # YAML emitted by `linkfetch parse`
+user_data_dir = "data/browser"  # persistent Chromium profile (keeps you logged in)
+
+[browser]
+headless = false             # show the window (needed for manual login)
+nav_timeout = 30             # seconds per navigation
+scroll_pause_ms = 600        # pause between scroll steps while loading lazy content
+max_scrolls = 40             # safety cap on scroll-to-bottom loops
+
+[linkedin]
+base_url = "https://www.linkedin.com"

linkfetch-0.1.0/docs/superpowers/specs/2026-06-15-linkfetch-design.md

@@ -0,0 +1,184 @@
+# linkfetch — Local LinkedIn Profile Scraper
+
+**Date:** 2026-06-15
+**Status:** Approved design, building
+
+## Purpose
+
+A **local CLI tool** that scrapes *your own* LinkedIn profile via browser
+automation and emits **`tailor`-compatible YAML**, so you can bootstrap or
+refresh your `tailor` profile from LinkedIn instead of typing it by hand.
+
+It is a sibling project under `prosperis`, decoupled from `tailor`: it knows
+`tailor`'s profile schema and writes matching YAML, but does not import or
+modify `tailor`. You review the emitted YAML and copy it into `tailor/data/profile/`.
+
+This is **not** a web service. Nothing is hosted; it is a command run on your
+machine that drives a real browser you log into.
+
+## Scope
+
+### Sections captured
+
+LinkedIn exposes far more than `tailor` models. We capture all of the
+following. Sections that map onto `tailor`'s schema are emitted as
+`tailor`-ready files; the rest are emitted as extra YAML for the user to handle.
+
+| LinkedIn section            | Output file              | Maps to tailor? |
+|-----------------------------|--------------------------|-----------------|
+| Name / headline / about / location | `basics.yaml`     | yes (`Basics`)  |
+| Experience                  | `experiences.yaml`       | yes (`Experience`) |
+| Skills                      | `skills.yaml`            | yes (`Skill`)   |
+| Projects                    | `projects.yaml`          | yes (`Project`) |
+| Licenses & certifications   | `certifications.yaml`    | yes (`Certification`) |
+| Honors & awards             | `awards.yaml`            | yes (`Award`)   |
+| Education                   | `education.yaml`         | no — extra      |
+| Volunteering                | `volunteering.yaml`      | no — extra      |
+| Recommendations             | `recommendations.yaml`   | no — extra      |
+| Patents                     | `patents.yaml`           | no — extra      |
+| Courses                     | `courses.yaml`           | no — extra      |
+| Languages                   | `languages.yaml`         | no — extra      |
+
+"Extra" files use a simple, readable schema of our own (defined in this repo),
+not `tailor`'s.
+
+### Out of scope
+
+- Scraping other people / companies / job postings (job postings are `tailor`'s job).
+- AI / Ollama normalization. **Pure deterministic scrape** — fields come straight
+  from the page. `summary` is raw text; `bullets` split on the page's own line
+  breaks; the user enriches tags / position framings later in `tailor`.
+- Official-export ZIP parsing.
+- Auto-writing into `tailor`'s profile dir (user reviews and copies manually).
+
+## Architecture — two-phase: capture HTML → parse offline
+
+The fragile part (LinkedIn's DOM, login, lazy loading) is **quarantined** in a
+capture phase that runs rarely and needs a live session. Parsing is a **pure
+function over saved HTML**, fully unit-testable against fixtures and re-runnable
+with no browser.
+
+```
+                 phase 1: capture (Playwright, live session)
+  LinkedIn  ──►  login (persistent context)  ──►  visit each section's
+                                                    /details/<section>/ page
+                                                  ──►  expand "see more", scroll
+                                                  ──►  save rendered HTML
+                                                       to captures/<section>.html
+                 ─────────────────────────────────────────────────────────────
+                 phase 2: parse (pure, no browser)
+  captures/*.html  ──►  per-section lxml parser  ──►  pydantic models
+                                                  ──►  YAML files in out/
+```
+
+### Components
+
+Package `linkfetch` under `src/linkfetch/` (mirrors `tailor`'s `src/` layout).
+
+- **`config.py`** — `Config` dataclass + `load_config()`, walking up for
+  `config.toml`, exactly like `tailor`. Paths: `captures_dir` (default
+  `data/captures`), `output_dir` (default `data/output`). Browser settings:
+  `user_data_dir` (persistent Chromium profile so login sticks),
+  `headless` (default false for login), `nav_timeout`.
+
+- **`capture/browser.py`** — Playwright session management. Launches a
+  **persistent context** (`launch_persistent_context(user_data_dir=...)`) so the
+  login cookie survives between runs. Exposes:
+  - `ensure_logged_in()` — open `linkedin.com/feed`, detect whether logged in;
+    if not, print instructions and wait for the user to log in manually, then
+    continue.
+  - `capture_section(section)` — navigate to the section's detail URL, run the
+    auto-expand routine, return rendered HTML.
+
+- **`capture/expand.py`** — the scroll + "…see more" / "Show all" expansion
+  routine, shared by all sections. Deterministic: scroll to bottom in steps
+  until height stops changing; click every visible expand control until none
+  remain. No section-specific logic here.
+
+- **`capture/sections.py`** — the registry of sections: slug, detail-page URL
+  template (e.g. `/in/{vanity}/details/experience/`), and which parser handles it.
+  The single source of truth for "what sections exist".
+
+- **`parse/` (one module per section)** — `experience.py`, `skills.py`,
+  `education.py`, etc. Each exposes `parse(html: str) -> list[Model]` (or a single
+  model for basics). Pure: `lxml` in, pydantic out. LinkedIn's randomized class
+  names are avoided by anchoring on **stable structures**: the visually-hidden
+  `<span aria-hidden="true">` text, `aria-label`s, and the section's anchor `id`.
+
+- **`models.py`** — pydantic models. For mapped sections, fields are a **subset**
+  of `tailor`'s models using the **same field names** (`id`, `summary`, `bullets`,
+  `tags`, `org`, `positions`, `timeline`, …) so emitted YAML drops into `tailor`.
+  For extra sections, small purpose-built models.
+
+- **`emit.py`** — serialize models to YAML using the same dumper settings as
+  `tailor`'s `store.py` (`sort_keys=False`, `allow_unicode=True`,
+  `default_flow_style=False`, `width=100`) so output is human-editable and
+  diffable, and identical in style to `tailor`'s files.
+
+- **`cli.py`** — `typer` app mirroring `tailor`'s style. Commands:
+  - `linkfetch doctor` — show config, whether Playwright is installed, whether a
+    login session exists.
+  - `linkfetch login` — open the browser and establish/refresh the session.
+  - `linkfetch capture [--section X ...] [--vanity NAME]` — phase 1; saves HTML
+    to `captures/`. Default: all sections.
+  - `linkfetch parse [--section X ...]` — phase 2; reads `captures/`, writes
+    YAML to `out/`. No browser needed.
+  - `linkfetch run` — convenience: `capture` then `parse`.
+
+### Data flow
+
+1. `login` → persistent Chromium profile stores the LinkedIn cookie under
+   `user_data_dir`.
+2. `capture` → for each section, navigate to its `/details/<section>/` page
+   (these are paginated and far simpler than the monolithic profile page),
+   expand everything, write `captures/<section>.html` + a `captures/meta.json`
+   (timestamp, vanity, section list).
+3. `parse` → for each captured section, run its parser, collect models, emit
+   `out/<file>.yaml`. Mapped files are byte-compatible with `tailor`; extra files
+   use local schemas.
+4. User reviews `out/`, copies the mapped YAML into `tailor/data/profile/`,
+   runs `tailor profile validate`.
+
+### Error handling
+
+- **Playwright missing** → `capture`/`login` fail with the same install hint
+  style `tailor` uses (`uv pip install playwright && playwright install chromium`).
+  `parse` and `doctor` still work without it.
+- **Not logged in** → `capture` detects the login wall and tells the user to run
+  `linkfetch login` (or logs in inline and waits).
+- **Section markup not recognized** → parser returns `[]` for that section and
+  records a warning in the run summary rather than crashing the whole run; the
+  raw HTML stays on disk so parsing can be retried after a selector fix.
+- **Partial captures** → `parse` only processes sections present in `captures/`;
+  missing ones are skipped with a note.
+
+### Testing
+
+- **Parsers (primary):** unit tests over **saved HTML fixtures** in
+  `tests/fixtures/<section>.html` (sanitized, anonymized snippets). Each parser
+  has a test asserting the structured output. This is where correctness lives and
+  is fully offline / CI-friendly.
+- **expand.py:** logic is browser-bound; covered by a thin smoke path, not unit
+  tested against live LinkedIn.
+- **emit.py:** round-trip test — models → YAML → re-load → equal; and a test that
+  mapped YAML validates against `tailor`'s pydantic models (import `tailor` as a
+  test-only dependency *if available*, else skip).
+- **config.py:** test root discovery and path resolution, mirroring `tailor`.
+
+TDD: write the failing parser test against a fixture first, then the parser.
+
+## Stack & conventions
+
+- Python ≥ 3.10, `uv`-managed venv, `pyproject.toml` with `hatchling`,
+  `src/linkfetch/` layout, `typer` + `rich` CLI, `pydantic` v2 models,
+  `pyyaml`, `lxml`. `playwright` is an **optional** extra (`[browser]`), exactly
+  like `tailor`. `pytest` + `pytest-mock` dev extra.
+- `config.toml` at project root; `data/` gitignored.
+- Console-script entry point `linkfetch = "linkfetch.cli:app"`.
+
+## Legal / safety note
+
+For **personal use on the user's own profile**. LinkedIn's ToS restricts
+automated access; this tool uses a real logged-in browser session at human-ish
+pace, captures only the authenticated user's own data, and stores nothing
+remotely. The README states this plainly.