From 3ca196b2d1319c0e8c95be7c3bdf0db677cf8dfd Mon Sep 17 00:00:00 2001
From: wuyangfan <1102042793@qq.com>
Date: Sun, 17 May 2026 23:23:29 +0800
Subject: [PATCH] docs: add in-repo Clara guide and fix stale links

Clara is developed inside Catch2; link own-main and opensource-users to
docs/clara.md instead of the archived external repository (fixes #2312).
---
 docs/clara.md            | 13 +++++++++++++
 docs/opensource-users.md |  4 ++--
 docs/own-main.md         |  3 +--
 3 files changed, 16 insertions(+), 4 deletions(-)
 create mode 100644 docs/clara.md

diff --git a/docs/clara.md b/docs/clara.md
new file mode 100644
index 0000000000..974721ccaf
--- /dev/null
+++ b/docs/clara.md
@@ -0,0 +1,13 @@
+# Clara (command-line parsing)
+
+Catch2 embeds **Clara** as `Catch::Clara` (`catch2/internal/catch_clara.hpp`). The
+standalone [Clara repository](https://github.com/catchorg/Clara) is archived;
+new development happens only inside Catch2.
+
+## Getting started
+
+- [Adding your own command line options](own-main.md#adding-your-own-command-line-options) —
+  extend Catch2's CLI with custom flags
+- [232-Cfg-CustomMain.cpp](../examples/232-Cfg-CustomMain.cpp) — full custom-`main`
+  example composing `Catch::Clara` with `Catch::Session`
+- [command-line.md](command-line.md) — built-in Catch2 flags and reporters
diff --git a/docs/opensource-users.md b/docs/opensource-users.md
index a02d0b98e2..81d7f60854 100644
--- a/docs/opensource-users.md
+++ b/docs/opensource-users.md
@@ -41,8 +41,8 @@ A, header-only, embedded scripting language designed from the ground up to direc
 ### [ChakraCore](https://github.com/Microsoft/ChakraCore)
 The core part of the Chakra JavaScript engine that powers Microsoft Edge.
 
-### [Clara](https://github.com/philsquared/Clara)
-A, single-header-only, type-safe, command line parser - which also prints formatted usage strings.
+### Clara (embedded in Catch2)
+Catch2's built-in type-safe command-line parser ([clara.md](clara.md)); formerly a separate project.
 
 ### [Couchbase-lite-core](https://github.com/couchbase/couchbase-lite-core)
 The next-generation core storage and query engine for Couchbase Lite.
diff --git a/docs/own-main.md b/docs/own-main.md
index 07cb49031a..b4c3e8980e 100644
--- a/docs/own-main.md
+++ b/docs/own-main.md
@@ -111,8 +111,7 @@ int main( int argc, char* argv[] ) {
 }
 ```
 
-See the [Clara documentation](https://github.com/catchorg/Clara/blob/master/README.md)
-for more details on how to use the Clara parser.
+See [clara.md](clara.md) for more details on the embedded `Catch::Clara` parser.
 
 
 ## Version detection