docs(community): showcase two external Opik projects + allow external proof_url (#56)

## What & why

Showcases two external, community-built projects that use Opik, as
**listed** entries in `community/`:

- **[Building a Coding Agent from Scratch
(course)](https://github.com/decodingai-magazine/building-a-coding-agent-from-scratch-course)**
— Paul Iusztin / Decoding AI. Opik is used for tracing + evals (Lesson
7).
- **[Observable Job
Agent](https://github.com/jamwithai/observable-job-agent)** — Shirin
Khosravi Jam / jamwithai. Observability-first CV→job-matching agent
instrumented with Opik from run one.

Both link out to the authors' own repos (`hosted: false`); no external
code is vendored in.

Since these are maintainer-added showcases (not author
self-submissions), we don't hold the authors' Opik screenshots. So this
PR also **relaxes the community proof rule**: an entry can now prove
Opik usage with an http(s) `proof_url` in `meta.yaml` (pointing at the
author's own trace screenshot / setup doc) as an alternative to a
committed `opik-proof.png`. The committed-PNG path is unchanged for
normal author submissions.

### Changes
- `community/_ci/entry_rules.py` — `validate_proof` accepts a
committed+referenced `opik-proof.png` **or** an http(s):// `proof_url`;
signature unchanged, PNG path behavior preserved.
- `community/_ci/tests/test_entry_rules.py` — new tests for the
`proof_url` accept path, the non-http reject, the scheme-less
(`httpfoo`) reject, and no-proof reject. Suite: 51 passing.
- `community/templates/entry-template/meta.yaml` +
`community/CONTRIBUTING.md` — document the optional `proof_url`.
- Two new listed entries (`paul_iusztin_coding_agent_course/`,
`jamwithai_observable_job_agent/`), each `meta.yaml` + `README.md`.
- `community/README.md` — regenerated by `build_index.py` (two-row
index).

Each `proof_url` points at a real, public page in the author's repo
showing Opik usage (a traces screenshot and an Opik setup/tracing doc,
respectively) — no fabricated proof.

## Checklist

<!-- The main-repo example contract (run.sh / litellm / uv / dry-run)
does not apply to community entries — see community/CONTRIBUTING.md. -->

- [x] Change confined to `community/` (its lighter-weight contract, not
the root example contract)
- [x] Folder names are `lowercase_with_underscores` and pass
`community/_ci/check_entry.py`
- [x] Both entries have all four required README sections and a valid
`meta.yaml`; `author` is the owning GitHub org so `github.com/<author>`
resolves
- [x] Proof of Opik usage present (real external `proof_url` for each)
- [x] `community/README.md` regenerated via `build_index.py` (`--check`
clean)
- [x] `python -m pytest -q` in `community/_ci` — 51 passing
- [x] No credentials or `.env` files committed

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Author: LeoRoccoBreedt

community/CONTRIBUTING.md

@@ -8,7 +8,10 @@ are not executed by CI; a maintainer reviews (and, for hosted entries, runs)
 them by hand.
 
 There is one thing we always require: **proof you actually logged with Opik** —
-either Comet cloud or the self-hosted open-source platform.
+either Comet cloud or the self-hosted open-source platform. Provide it one of
+two ways: commit an `opik-proof.png` screenshot referenced from your `README.md`
+(the default for authors), or set an http(s) `proof_url` in `meta.yaml` pointing
+at your screenshot (used mainly when a maintainer showcases an external project).
 
 ## Two kinds of entry
 
@@ -42,7 +45,8 @@ run your code. It checks:
 - `meta.yaml` has all required fields, at least one link, and a valid
   `opik_platform`.
 - `README.md` has all four sections filled in (no leftover `TODO`).
-- `opik-proof.png` exists and is referenced from your README.
+- Proof of Opik usage exists: either `opik-proof.png` (referenced from your
+  README) or an http(s) `proof_url` in `meta.yaml`.
 - No `.env` file or hardcoded API keys are committed.
 - Hosted entries contain code that uses Opik.
 - The folder name is `lowercase_with_underscores`.

community/README.md

@@ -9,4 +9,7 @@ are hosted in-repo (see the Hosted column).
 
 To add your own, see [CONTRIBUTING.md](CONTRIBUTING.md).
 
-_No community contributions yet — be the first!_
+| Project | Author | Description | Platform | Links | Hosted | Tags |
+|---|---|---|---|---|---|---|
+| [Building a Coding Agent from Scratch (course)](paul_iusztin_coding_agent_course/) | [@decodingai-magazine](https://github.com/decodingai-magazine) | An open-source course that builds a terminal coding agent from scratch, using Opik for tracing and evals. | cloud | [repo](https://github.com/decodingai-magazine/building-a-coding-agent-from-scratch-course) |  | agent, course, coding-agent, evaluation, observability |
+| [Observable Job Agent](jamwithai_observable_job_agent/) | [@jamwithai](https://github.com/jamwithai) | An observability-first CV-to-job-matching agent, instrumented with Opik from run one. | cloud | [repo](https://github.com/jamwithai/observable-job-agent) |  | agent, langgraph, observability, rag |

community/_ci/entry_rules.py

@@ -107,15 +107,27 @@ def validate_readme(entry: Path) -> list[str]:
 
 
 def validate_proof(entry: Path) -> list[str]:
-    errors: list[str] = []
-    if not (entry / "opik-proof.png").is_file():
-        errors.append(f"{entry.name}: missing opik-proof.png (screenshot of your Opik traces)")
-        return errors
     readme_path = entry / "README.md"
-    text = readme_path.read_text(encoding="utf-8") if readme_path.is_file() else ""
-    if "opik-proof.png" not in text:
-        errors.append(f"{entry.name}: opik-proof.png must be referenced from README.md")
-    return errors
+    readme_text = readme_path.read_text(encoding="utf-8") if readme_path.is_file() else ""
+
+    png_path = entry / "opik-proof.png"
+    if png_path.is_file():
+        if "opik-proof.png" not in readme_text:
+            return [f"{entry.name}: opik-proof.png must be referenced from README.md"]
+        return []
+
+    # meta errors are reported by validate_meta; {} here falls through to the no-proof error
+    data, _ = load_meta(entry)
+    proof_url = data.get("proof_url")
+    if _nonempty_str(proof_url) and str(proof_url).startswith(("http://", "https://")):
+        return []
+
+    return [
+        (
+            f"{entry.name}: no proof of Opik usage — commit an opik-proof.png referenced "
+            f"from README.md, or set an http(s) 'proof_url' in meta.yaml"
+        )
+    ]
 
 
 _FOLDER_NAME_RE = re.compile(r"^[a-z0-9]+(?:_[a-z0-9]+)+$")
@@ -132,8 +144,10 @@ def validate_proof(entry: Path) -> list[str]:
 def validate_folder_name(entry: Path) -> list[str]:
     if not _FOLDER_NAME_RE.match(entry.name):
         return [
-            f"{entry.name}: folder name must be lowercase '<author>_<project>' "
-            f"(letters/digits/underscores, at least one underscore)"
+            (
+                f"{entry.name}: folder name must be lowercase '<author>_<project>' "
+                f"(letters/digits/underscores, at least one underscore)"
+            )
         ]
     return []
 
@@ -180,6 +194,8 @@ def validate_code_uses_opik(entry: Path) -> list[str]:
             if any(marker in text for marker in _OPIK_MARKERS):
                 return []
     return [
-        f"{entry.name}: hosted entry has no code that uses Opik "
-        f"(expected one of: import opik, @opik.track, opik.Opik(, OPIK_)"
+        (
+            f"{entry.name}: hosted entry has no code that uses Opik "
+            f"(expected one of: import opik, @opik.track, opik.Opik(, OPIK_)"
+        )
     ]

community/_ci/tests/test_entry_rules.py

@@ -212,3 +212,42 @@ def test_non_ascii_readme_and_meta_are_read_as_utf8(tmp_path: Path):
     )
     assert validate_readme(entry) == []
     assert validate_meta(entry) == []
+
+
+def test_proof_url_without_png_passes(tmp_path: Path):
+    readme = (
+        "# T\n\n## What I built\nA.\n\n## Problem it solves\nB.\n\n"
+        "## What I learned\nC.\n\n## How I used Opik\n"
+        "See the author's traces: https://example.com/opik.png\n"
+    )
+    entry = write_entry(
+        tmp_path,
+        readme=readme,
+        include_png=False,
+        meta={"proof_url": "https://example.com/opik.png"},
+    )
+    assert validate_proof(entry) == []
+
+
+def test_non_http_proof_url_without_png_is_error(tmp_path: Path):
+    entry = write_entry(
+        tmp_path,
+        include_png=False,
+        meta={"proof_url": "see my repo"},
+    )
+    assert any("proof" in e.lower() for e in validate_proof(entry))
+
+
+def test_schemeless_http_proof_url_without_png_is_error(tmp_path: Path):
+    entry = write_entry(
+        tmp_path,
+        include_png=False,
+        meta={"proof_url": "httpfoo-not-a-url"},
+    )
+    assert any("proof" in e.lower() for e in validate_proof(entry))
+
+
+def test_no_png_and_no_proof_url_is_error(tmp_path: Path):
+    entry = write_entry(tmp_path, include_png=False)
+    errors = validate_proof(entry)
+    assert any("opik-proof.png" in e or "proof_url" in e for e in errors)

community/jamwithai_observable_job_agent/README.md

@@ -0,0 +1,33 @@
+# Observable Job Agent
+
+A community showcase of [Observable Job Agent](https://github.com/jamwithai/observable-job-agent),
+an open-source project by Shirin Khosravi Jam (jamwithai). We link to it here to
+spotlight how the community uses Opik — the code lives in the author's repo.
+
+## What I built
+An MIT-licensed AI job-matching agent you run locally: upload a CV (PDF) and it
+produces a typed profile, searches real job listings across multiple sources, and
+ranks each posting with a 0–100 fit score plus an explanation of matches and gaps.
+It is built on LangGraph (agent graph + a bounded reformulation loop) with a Gradio
+three-step wizard, and it's Part 1 ("Build") of a "Build → Evaluate → Self-Improve"
+series.
+
+## Problem it solves
+Job seekers waste hours manually judging whether a posting fits their background.
+This agent turns that into a structured, explainable ranking — and does it in a way
+whose cost, latency, and quality are measurable, so the agent can later be evaluated
+and improved rather than trusted blindly.
+
+## What I learned
+The project's thesis is that observability comes first: the agent is instrumented
+*before* it is made good, so cost, latency, and quality are measurable from run one.
+That ordering makes Opik a design tool, not an afterthought — the span tree and
+agent graph reveal how each node behaves as the graph evolves.
+
+## How I used Opik
+Opik (Comet) provides a span tree per LangGraph node, an auto-drawn agent graph, and
+per-run cost tracking; each run attaches the uploaded CV plus metadata (git SHA,
+model, job counts) and tags, and prompts are registered and versioned in Opik's
+prompt library. The Gradio run footer surfaces cost, latency, and a trace link. See
+the author's Opik setup and tracing guide:
+https://github.com/jamwithai/observable-job-agent/blob/main/docs/opik_setup.md

community/jamwithai_observable_job_agent/meta.yaml

@@ -0,0 +1,9 @@
+title: Observable Job Agent
+description: An observability-first CV-to-job-matching agent, instrumented with Opik from run one.
+author: jamwithai
+links:
+  repo: https://github.com/jamwithai/observable-job-agent
+opik_platform: cloud
+proof_url: https://github.com/jamwithai/observable-job-agent/blob/main/docs/opik_setup.md
+tags: [agent, langgraph, observability, rag]
+hosted: false

community/paul_iusztin_coding_agent_course/README.md

@@ -0,0 +1,30 @@
+# Building a Coding Agent from Scratch (course)
+
+A community showcase of [Building a Coding Agent from Scratch](https://github.com/decodingai-magazine/building-a-coding-agent-from-scratch-course),
+an open-source course by Paul Iusztin (Decoding AI). We link to it here to spotlight
+how the community uses Opik — the code lives in the author's repo.
+
+## What I built
+A project-based, Apache-2.0 course that walks engineers from a ~20-line agent loop
+to cloud-deployed subagent swarms. Across eight lessons it builds "the harness"
+around a coding agent — permissions, sandboxes, context compaction, subagent
+fan-out, a durable runtime, and evals — on a Pydantic AI ReAct loop with
+file/bash/web/LSP tools and Docker/Modal sandboxes.
+
+## Problem it solves
+Most agent tutorials stop at the model call. This course targets the harder,
+production-shaped problem: the engineering *around* the model that makes a coding
+agent safe, observable, and reliable — the part teams actually have to build.
+
+## What I learned
+Opik is wired in as an `observability/` module so every session is traced, with
+secrets scrubbed before they reach a log. Lesson 7 ("Benchmarks, regression probes,
+and online evals") shows how tracing feeds an eval suite, making agent behavior
+measurable rather than anecdotal as the harness grows.
+
+## How I used Opik
+Each agent session is traced end-to-end (Opik threads), and the course's eval suite
+runs benchmarks, regression probes, and online evals against those traces. Opik
+(Comet) is a course sponsor and runs on the free tier. See the author's Opik
+threads screenshot:
+https://github.com/decodingai-magazine/building-a-coding-agent-from-scratch-course/blob/main/assets/opik-threads.png

community/paul_iusztin_coding_agent_course/meta.yaml

@@ -0,0 +1,9 @@
+title: Building a Coding Agent from Scratch (course)
+description: An open-source course that builds a terminal coding agent from scratch, using Opik for tracing and evals.
+author: decodingai-magazine
+links:
+  repo: https://github.com/decodingai-magazine/building-a-coding-agent-from-scratch-course
+opik_platform: cloud
+proof_url: https://github.com/decodingai-magazine/building-a-coding-agent-from-scratch-course/blob/main/assets/opik-threads.png
+tags: [agent, course, coding-agent, evaluation, observability]
+hosted: false

community/templates/entry-template/meta.yaml

@@ -5,6 +5,11 @@ author: your-github-handle
 links:
   repo: https://github.com/your-handle/your-project   # at least one http(s) link required
   # blog: https://...                                 # optional extra links
+# proof_url: https://github.com/your-handle/your-project/blob/main/assets/opik.png
+#                                             # optional: link to a screenshot of your
+#                                             # Opik traces INSTEAD of committing
+#                                             # opik-proof.png (used mainly when a
+#                                             # maintainer showcases an external project)
 opik_platform: cloud        # cloud | self-hosted
 tags: [agent, rag]          # free-form; may be empty []
 hosted: false               # leave false; a maintainer sets this true when promoting