@lydt/geogebra-studio 0.0.0-stage → 0.4.0-rc.2

package/.agents/plugins/marketplace.json

@@ -0,0 +1,21 @@
+{
+  "name": "geogebra-studio",
+  "interface": {
+    "displayName": "GeoGebra Studio"
+  },
+  "plugins": [
+    {
+      "name": "geogebra-studio",
+      "source": {
+        "source": "npm",
+        "package": "@lydt/geogebra-studio",
+        "version": "0.4.0-rc.2"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Education"
+    }
+  ]
+}

package/.codex-plugin/plugin.json

@@ -0,0 +1,21 @@
+{
+  "name": "geogebra-studio",
+  "version": "0.4.0-rc.2",
+  "description": "GeoGebra Studio: editable geometry plugin with MCP, agent skills, interactive HTML and built-in Gikz",
+  "skills": "./skills/",
+  "mcpServers": "./.mcp.json",
+  "extensions": {
+    "com.openai": {
+      "onboardingSkill": "./skills/geogebra-setup/SKILL.md",
+      "interface": {
+        "displayName": "GeoGebra Studio",
+        "shortDescription": "Editable geometry, interactive HTML and cleaned TikZ",
+        "developerName": "YZDame",
+        "category": "Education",
+        "defaultPrompt": [
+          "Construct an editable GeoGebra diagram from this problem and deliver a local HTML."
+        ]
+      }
+    }
+  }
+}

package/.mcp.json

@@ -0,0 +1,18 @@
+{
+  "mcpServers": {
+    "geogebra": {
+      "command": "npx",
+      "args": [
+        "--yes",
+        "--prefix",
+        "./runtime",
+        "@lydt/geogebra-studio@0.4.0-rc.2",
+        "mcp"
+      ],
+      "env": {
+        "GEOGEBRA_TOOL_PROFILE": "core",
+        "GEOGEBRA_PLUGIN_RUNTIME": "1"
+      }
+    }
+  }
+}

package/LICENSE

@@ -0,0 +1,339 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 2, June 1991
+
+ Copyright (C) 1989, 1991 Free Software Foundation, Inc.,
+ 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The licenses for most software are designed to take away your
+freedom to share and change it.  By contrast, the GNU General Public
+License is intended to guarantee your freedom to share and change free
+software--to make sure the software is free for all its users.  This
+General Public License applies to most of the Free Software
+Foundation's software and to any other program whose authors commit to
+using it.  (Some other Free Software Foundation software is covered by
+the GNU Lesser General Public License instead.)  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+this service if you wish), that you receive source code or can get it
+if you want it, that you can change the software or use pieces of it
+in new free programs; and that you know you can do these things.
+
+  To protect your rights, we need to make restrictions that forbid
+anyone to deny you these rights or to ask you to surrender the rights.
+These restrictions translate to certain responsibilities for you if you
+distribute copies of the software, or if you modify it.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must give the recipients all the rights that
+you have.  You must make sure that they, too, receive or can get the
+source code.  And you must show them these terms so they know their
+rights.
+
+  We protect your rights with two steps: (1) copyright the software, and
+(2) offer you this license which gives you legal permission to copy,
+distribute and/or modify the software.
+
+  Also, for each author's protection and ours, we want to make certain
+that everyone understands that there is no warranty for this free
+software.  If the software is modified by someone else and passed on, we
+want its recipients to know that what they have is not the original, so
+that any problems introduced by others will not reflect on the original
+authors' reputations.
+
+  Finally, any free program is threatened constantly by software
+patents.  We wish to avoid the danger that redistributors of a free
+program will individually obtain patent licenses, in effect making the
+program proprietary.  To prevent this, we have made it clear that any
+patent must be licensed for everyone's free use or not licensed at all.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                    GNU GENERAL PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. This License applies to any program or other work which contains
+a notice placed by the copyright holder saying it may be distributed
+under the terms of this General Public License.  The "Program", below,
+refers to any such program or work, and a "work based on the Program"
+means either the Program or any derivative work under copyright law:
+that is to say, a work containing the Program or a portion of it,
+either verbatim or with modifications and/or translated into another
+language.  (Hereinafter, translation is included without limitation in
+the term "modification".)  Each licensee is addressed as "you".
+
+Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope.  The act of
+running the Program is not restricted, and the output from the Program
+is covered only if its contents constitute a work based on the
+Program (independent of having been made by running the Program).
+Whether that is true depends on what the Program does.
+
+  1. You may copy and distribute verbatim copies of the Program's
+source code as you receive it, in any medium, provided that you
+conspicuously and appropriately publish on each copy an appropriate
+copyright notice and disclaimer of warranty; keep intact all the
+notices that refer to this License and to the absence of any warranty;
+and give any other recipients of the Program a copy of this License
+along with the Program.
+
+You may charge a fee for the physical act of transferring a copy, and
+you may at your option offer warranty protection in exchange for a fee.
+
+  2. You may modify your copy or copies of the Program or any portion
+of it, thus forming a work based on the Program, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:
+
+    a) You must cause the modified files to carry prominent notices
+    stating that you changed the files and the date of any change.
+
+    b) You must cause any work that you distribute or publish, that in
+    whole or in part contains or is derived from the Program or any
+    part thereof, to be licensed as a whole at no charge to all third
+    parties under the terms of this License.
+
+    c) If the modified program normally reads commands interactively
+    when run, you must cause it, when started running for such
+    interactive use in the most ordinary way, to print or display an
+    announcement including an appropriate copyright notice and a
+    notice that there is no warranty (or else, saying that you provide
+    a warranty) and that users may redistribute the program under
+    these conditions, and telling the user how to view a copy of this
+    License.  (Exception: if the Program itself is interactive but
+    does not normally print such an announcement, your work based on
+    the Program is not required to print an announcement.)
+
+These requirements apply to the modified work as a whole.  If
+identifiable sections of that work are not derived from the Program,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works.  But when you
+distribute the same sections as part of a whole which is a work based
+on the Program, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote it.
+
+Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Program.
+
+In addition, mere aggregation of another work not based on the Program
+with the Program (or with a work based on the Program) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.
+
+  3. You may copy and distribute the Program (or a work based on it,
+under Section 2) in object code or executable form under the terms of
+Sections 1 and 2 above provided that you also do one of the following:
+
+    a) Accompany it with the complete corresponding machine-readable
+    source code, which must be distributed under the terms of Sections
+    1 and 2 above on a medium customarily used for software interchange; or,
+
+    b) Accompany it with a written offer, valid for at least three
+    years, to give any third party, for a charge no more than your
+    cost of physically performing source distribution, a complete
+    machine-readable copy of the corresponding source code, to be
+    distributed under the terms of Sections 1 and 2 above on a medium
+    customarily used for software interchange; or,
+
+    c) Accompany it with the information you received as to the offer
+    to distribute corresponding source code.  (This alternative is
+    allowed only for noncommercial distribution and only if you
+    received the program in object code or executable form with such
+    an offer, in accord with Subsection b above.)
+
+The source code for a work means the preferred form of the work for
+making modifications to it.  For an executable work, complete source
+code means all the source code for all modules it contains, plus any
+associated interface definition files, plus the scripts used to
+control compilation and installation of the executable.  However, as a
+special exception, the source code distributed need not include
+anything that is normally distributed (in either source or binary
+form) with the major components (compiler, kernel, and so on) of the
+operating system on which the executable runs, unless that component
+itself accompanies the executable.
+
+If distribution of executable or object code is made by offering
+access to copy from a designated place, then offering equivalent
+access to copy the source code from the same place counts as
+distribution of the source code, even though third parties are not
+compelled to copy the source along with the object code.
+
+  4. You may not copy, modify, sublicense, or distribute the Program
+except as expressly provided under this License.  Any attempt
+otherwise to copy, modify, sublicense or distribute the Program is
+void, and will automatically terminate your rights under this License.
+However, parties who have received copies, or rights, from you under
+this License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+  5. You are not required to accept this License, since you have not
+signed it.  However, nothing else grants you permission to modify or
+distribute the Program or its derivative works.  These actions are
+prohibited by law if you do not accept this License.  Therefore, by
+modifying or distributing the Program (or any work based on the
+Program), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Program or works based on it.
+
+  6. Each time you redistribute the Program (or any work based on the
+Program), the recipient automatically receives a license from the
+original licensor to copy, distribute or modify the Program subject to
+these terms and conditions.  You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties to
+this License.
+
+  7. If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Program at all.  For example, if a patent
+license would not permit royalty-free redistribution of the Program by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Program.
+
+If any portion of this section is held invalid or unenforceable under
+any particular circumstance, the balance of the section is intended to
+apply and the section as a whole is intended to apply in other
+circumstances.
+
+It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system, which is
+implemented by public license practices.  Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.
+
+This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.
+
+  8. If the distribution and/or use of the Program is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Program under this License
+may add an explicit geographical distribution limitation excluding
+those countries, so that distribution is permitted only in or among
+countries not thus excluded.  In such case, this License incorporates
+the limitation as if written in the body of this License.
+
+  9. The Free Software Foundation may publish revised and/or new versions
+of the General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+Each version is given a distinguishing version number.  If the Program
+specifies a version number of this License which applies to it and "any
+later version", you have the option of following the terms and conditions
+either of that version or of any later version published by the Free
+Software Foundation.  If the Program does not specify a version number of
+this License, you may choose any version ever published by the Free Software
+Foundation.
+
+  10. If you wish to incorporate parts of the Program into other free
+programs whose distribution conditions are different, write to the author
+to ask for permission.  For software which is copyrighted by the Free
+Software Foundation, write to the Free Software Foundation; we sometimes
+make exceptions for this.  Our decision will be guided by the two goals
+of preserving the free status of all derivatives of our free software and
+of promoting the sharing and reuse of software generally.
+
+                            NO WARRANTY
+
+  11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
+FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
+OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
+PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
+OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
+TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
+PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
+REPAIR OR CORRECTION.
+
+  12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
+REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
+INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
+OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
+TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
+YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
+PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software; you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation; either version 2 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License along
+    with this program; if not, write to the Free Software Foundation, Inc.,
+    51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+Also add information on how to contact you by electronic and paper mail.
+
+If the program is interactive, make it output a short notice like this
+when it starts in an interactive mode:
+
+    Gnomovision version 69, Copyright (C) year name of author
+    Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License.  Of course, the commands you use may
+be called something other than `show w' and `show c'; they could even be
+mouse-clicks or menu items--whatever suits your program.
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a "copyright disclaimer" for the program, if
+necessary.  Here is a sample; alter the names:
+
+  Yoyodyne, Inc., hereby disclaims all copyright interest in the program
+  `Gnomovision' (which makes passes at compilers) written by James Hacker.
+
+  <signature of Ty Coon>, 1 April 1989
+  Ty Coon, President of Vice
+
+This General Public License does not permit incorporating your program into
+proprietary programs.  If your program is a subroutine library, you may
+consider it more useful to permit linking proprietary applications with the
+library.  If this is what you want to do, use the GNU Lesser General
+Public License instead of this License.

package/LICENSE-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Efe Baysal
+
+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.

package/README.md

@@ -1,3 +1,109 @@
-# Temporary Holding Version
+# GeoGebra Studio
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> Release status: `0.4.0` is undergoing release validation. The local plugin passed fresh-session MCP discovery and tool invocation. Candidate versions are distributed under the npm `next` tag (`npx @lydt/geogebra-studio@next install`); public marketplace installation and platform checks must pass before the stable release.
+
+A local Codex plugin combining **MCP tools, agent skills, an editable GeoGebra HTML
+viewer, and built-in Gikz**. Describe a geometry problem; get a local HTML carrying
+a packed, editable GGB, then modify objects and download the current construction.
+
+[中文](README.zh-CN.md) · [Visual standard](docs/VISUAL-STANDARD.md) · [Regression](docs/TANGENT-REGRESSION.md)
+
+## Install the complete plugin
+
+Requires Node >=22.12.0, npm/npx and a Codex installation supporting plugin commands.
+
+```sh
+npx @lydt/geogebra-studio install
+```
+
+Installation registers a persistent, version-pinned npm marketplace and installs
+both skills and MCP through Codex. It probes existing Chrome; if none is usable,
+it downloads managed Chromium. No GeoGebra desktop app or external Gikz is needed.
+Start a **new Codex session**, invoke `@geogebra-studio`, and describe the problem.
+
+```text
+Draw Gamma: x²+y²=25 and omega: (x−3)²+y²=64/25. A moves on Gamma.
+The two tangents from A to omega meet Gamma again at B and C.
+Deliver an editable local HTML with labels O, I, A, B, C, Γ and ω.
+```
+
+The agent uses `geogebra_build_artifact`: execute native commands, check visible
+objects, embed packed GGB, reopen the final viewer, check equal axes and return a
+preview for visual review. Output files are new files within the workspace; existing
+files are not overwritten. The example commands are in
+[examples/tangent-construction.json](examples/tangent-construction.json).
+The agent passes the absolute user project directory as `workspace` when saving;
+clients can also supply MCP roots. Output is never silently directed into the plugin cache.
+
+## Edit and download
+
+Open the HTML in a browser, drag A, or expand the left object sidebar to change
+original definitions/styles. Theme, light/dark and download buttons sit at the
+upper right. Nine paired themes are included.
+
+| Download | What it preserves |
+| --- | --- |
+| GGB | Native editable construction, relationships and styling |
+| HTML | Packed GGB, interactive viewer, themes and local cleaner |
+| XML | GeoGebra definitions and styles; not a packed GGB |
+| SVG / PDF | Static vector rendering |
+| PNG | Static raster rendering |
+| TikZ (.tex) | Native PGF passed through Gikz; normalized static source |
+
+**Every TikZ export uses native PGF → built-in Gikz → .tex.** This includes viewer
+downloads, geogebra_export_tikz, geogebra_export_source(format=tikz), and the generic
+exportPGF bridge. Failure is an error, with no raw fallback. Gikz normalizes colors,
+widths, label placement and precision; construction dependencies remain in GGB/XML.
+Asymptote and mixed TSQX/Asymptote retain the existing explicit semantic subset and
+strict/partial warnings. General relation reconstruction still requires review.
+
+## MCP-only and diagnostics
+
+```sh
+npx @lydt/geogebra-studio mcp          # MCP only; no-argument invocation also works
+npx @lydt/geogebra-studio doctor       # Browser launch and built-in Gikz check
+npx @lydt/geogebra-studio browser install
+```
+
+`mcp` alone does not install skills. PUPPETEER_EXECUTABLE_PATH selects a custom Chrome.
+GEOGEBRA_STUDIO_HOME controls Studio's browser cache; CODEX_HOME controls Codex's
+persistent catalog location. Never configure an ephemeral npx directory as a plugin.
+The plugin's MCP configuration invokes the exact matching package version.
+
+Native execution and opening the viewer require official GeoGebra network assets.
+Generated HTML is a local file, not a fully offline GeoGebra distribution. Gikz
+cleanup is local and makes no network request. Loading errors are shown explicitly.
+The initial release targets local Codex, not a hosted ChatGPT endpoint/public listing.
+
+## Develop and validate
+
+```sh
+npm ci --ignore-scripts
+npm run build
+npm run test:unit
+npm run verify
+npm run verify:native
+```
+
+Native/browser checks need Chrome and internet. `node scripts/verify-viewer.cjs`
+checks responsive geometry, native sidebar editing and seven downloads;
+`node scripts/verify-gikz-mcp.cjs` checks the actual MCP TikZ routes.
+Build outputs and all licenses ship in npm and versioned plugin ZIP artifacts.
+Published marketplace packages do not rely on install-time build/lifecycle scripts.
+For unpublished authoring, `node dist/cli.js install --local` installs a stable local
+copy; use a fresh CODEX_HOME to isolate a test installation. Source-build validation
+and an SDK handshake alone do not establish real plugin loading in a fresh session.
+
+## Migration and licensing
+
+GeoGebra Studio succeeds @lydt/geogebra-mcp-server and plugin geogebra-geometry.
+Existing geogebra_* tool names and the geogebra-mcp binary alias remain. Install the
+new plugin, verify it in a new session, then remove the old one if desired; the
+installer does not remove it automatically. GIKZ_CLI is no longer needed or used.
+The GitHub repository URL remains valid under its original name until its owner
+renames it; package branding does not require an immediate repository rename.
+
+The combined distribution is GPL-2.0-or-later. Original MCP portions retain their
+MIT notices in LICENSE-MIT; Gikz's upstream attribution and source are in gikz/.
+Clipper-derived palettes retain their MIT notices in THIRD_PARTY_NOTICES.md.
+This plugin is independently maintained and is not an official GeoGebra product.

package/README.zh-CN.md

@@ -0,0 +1,89 @@
+# GeoGebra Studio
+
+> 发布状态：`0.4.0` 正在进行发布验收。本地插件已通过全新会话中的 MCP 发现和工具调用。候选版使用 npm `next` 标签（`npx @lydt/geogebra-studio@next install`）；公共 marketplace 安装和平台验收通过后发布正式版。
+
+将 **MCP、agent skills、可编辑 GeoGebra HTML 查看器与内置 Gikz** 打包在一起的
+本地 Codex 插件。描述几何题，获得内嵌真正 GGB 的本地 HTML，随后编辑与下载。
+
+[English](README.md) · [视觉规范](docs/VISUAL-STANDARD.md) · [回归案例](docs/TANGENT-REGRESSION.md)
+
+## 安装完整插件
+
+需要 Node ≥22.12.0、npm/npx，以及支持 plugin 命令的 Codex。
+
+```sh
+npx @lydt/geogebra-studio install
+```
+
+安装器登记持久化、固定版本的 npm marketplace，通过 Codex 安装 skills 和 MCP。
+优先检测并试启动现有 Chrome；没有可用版本时下载受管理的 Chromium。
+不需要 GeoGebra 桌面客户端，也不需要单独安装 Gikz。
+安装后开启**新会话**，引用 `@geogebra-studio` 并描述题意，例如：
+
+> 画圆 Γ：x²+y²=25 与圆 ω：(x−3)²+y²=64/25。A 在 Γ 上运动，过 A 作 ω 的两条
+> 切线，与 Γ 再交于 B、C。生成可编辑的本地 HTML，标注 O、I、A、B、C、Γ、ω。
+
+默认工具 `geogebra_build_artifact` 执行原生构造、检查可见对象、打包 GGB，重新
+打开最终 HTML 并检查等比画布，返回预览供 agent 检查。仅创建工作区内新文件，
+不会覆盖已有文件。完整参数见 examples/tangent-construction.json。
+保存文件时，agent 将用户项目的绝对目录传入 `workspace`；客户端也可以提供 MCP roots。
+输出文件不会默认落入插件缓存目录。
+
+## 编辑与下载
+
+打开 HTML 后可拖动 A；左侧按钮展开原生对象栏，可修改定义与样式。
+右上角有主题菜单、独立深浅色切换和下载菜单，提供九组配色。
+
+| 格式 | 内容 |
+| --- | --- |
+| GGB | 原生可编辑对象、构造关系和样式 |
+| HTML | GGB、交互查看器、主题和本地清洗器 |
+| XML | GeoGebra 定义与样式，不是打包 GGB |
+| SVG / PDF | 静态矢量图 |
+| PNG | 静态位图 |
+| TikZ | 原生 PGF 经 Gikz 清洗的静态源码 |
+
+所有 TikZ 入口统一经过**原生 PGF → 内置 Gikz → .tex**；清洗失败报错，没有原始
+代码回退。清洗会规范化颜色、线宽、坐标精度及标签位置；完整构造关系保存在
+GGB/XML。Asymptote 与混合 TSQX/Asymptote 保留原有语义子集及 strict/partial 警告，
+一般构造关系的转换仍需检查。
+
+## 单独启动 MCP 与诊断
+
+```sh
+npx @lydt/geogebra-studio mcp
+npx @lydt/geogebra-studio doctor
+npx @lydt/geogebra-studio browser install
+```
+
+无参数也启动 MCP；单独运行 MCP 不会安装 skills。
+PUPPETEER_EXECUTABLE_PATH 可指定 Chrome；GEOGEBRA_STUDIO_HOME 控制浏览器缓存，
+CODEX_HOME 控制 Codex 持久化目录。插件配置绑定同版本 npm 包，不指向临时 npx 目录。
+
+执行原生构造、打开 HTML 均需要联网加载 GeoGebra 官方资源；HTML 不是完整离线版
+GeoGebra。Gikz 本地清洗不上传图形。加载失败会显示具体错误。
+首发面向本地 Codex，不包含远程 HTTPS 服务或 ChatGPT 公共目录上架。
+
+## 开发、验收与迁移
+
+```sh
+npm ci --ignore-scripts
+npm run build
+npm run test:unit
+npm run verify
+npm run verify:native
+```
+
+真实引擎/浏览器检查需要 Chrome 和网络。verify-viewer.cjs 检查响应式画布、原生
+对象栏编辑与七种下载；verify-gikz-mcp.cjs 检查实际 MCP TikZ 出口。
+npm 和 plugin ZIP 包携带构建结果、源码及许可证，不依赖安装时编译。
+未发布的开发测试可运行 `node dist/cli.js install --local`，使用独立 CODEX_HOME
+隔离测试；SDK 调通或源码构建成功，均不能代替新会话中的插件加载验收。
+
+新包替代 @lydt/geogebra-mcp-server 与 geogebra-geometry 插件，保留 geogebra_* 工具名
+和 geogebra-mcp 命令别名。新插件验收后可手动删除旧插件；安装器不会自动卸载。
+不再使用 GIKZ_CLI。GitHub 仓库由维护者后续改名，届时更新链接。
+
+融合发行版采用 GPL-2.0-or-later。原 MCP 的 MIT 声明保留在 LICENSE-MIT，Gikz
+源码及来源保存在 gikz/，Clipper 配色的 MIT 声明保留在 THIRD_PARTY_NOTICES.md。
+本插件独立维护，并非 GeoGebra 官方产品。

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,35 @@
+# Obsidian Clipper reader theme palettes
+
+Source: https://github.com/obsidianmd/obsidian-clipper/blob/main/src/styles/_reader-themes.scss
+
+MIT License
+
+Copyright (c) 2024 Obsidian
+
+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.
+
+## Built-in Gikz
+Gikz is now part of this GPL-2.0-or-later distribution. See gikz/LICENSE and
+gikz/PROVENANCE.md for its imported revision and upstream By990920 attribution.
+The same source core is used by MCP, CLI and the browser bundle. Generated HTML
+includes executable cleaner source and its full GPL license; preserve these notices.
+
+## Original MCP
+Original MIT notices remain in LICENSE-MIT. Combined distribution does not remove
+or replace those original copyright notices.