doc: Update documentation

docs/api-data.rst

@@ -1,5 +1,5 @@
 Data
 =============
 
-.. automodule:: pantograph.compiler
+.. automodule:: pantograph.data
     :members:

docs/goal.ipynb

@@ -214,7 +214,9 @@
     "\n",
     "Lean has special provisions for some tactics. This includes `have`, `let`,\n",
     "`calc`. To execute one of these tactics, create a `TacticHave`, `TacticLet`,\n",
-    "`TacticCalc` instance and feed it into `server.goal_tactic`"
+    "`TacticCalc` instance and feed it into `server.goal_tactic`.\n",
+    "\n",
+    "Technically speaking `have` and `let` are not tactics in Lean, so their execution requires special attention."
    ]
   },
   {
@@ -307,7 +309,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.12.6"
+   "version": "3.12.7"
   }
  },
  "nbformat": 4,

docs/intro.md

@@ -23,6 +23,38 @@ Almost all of Pantograph's business logic is written in Lean, and Pantograph
 achieves tighter coupling between the data extraction and proof search
 components.
 
+## Caveats and Limitations
+
+Pantograph does not exactly mimic Lean LSP's behaviour. That would not grant the
+flexibility it offers.  To support tree search means Pantograph has to act
+differently from Lean in some times, but never at the sacrifice of soundness.
+
+- When Lean LSP says "don't know how to synthesize placeholder", this indicates
+  the human operator needs to manually move the cursor to the placeholder and
+  type in the correct expression. This error therefore should not halt the proof
+  process, and the placeholder should be turned into a goal.
+- When Lean LSP says "unresolved goals", that means a proof cannot finish where
+  it is supposed to finish at the end of a `by` block. Pantograph will raise the
+  error in this case, since it indicates the termination of a proof search branch.
+- `pick_goal` or `swap` will not work since they run contrary to tree search
+  paradigms. However, if there are tactics which perform non-trivial operations
+  to multiple goals at the same time, this constrain could potentially be
+  relaxed at a cost of great bookkeeping overhead to the user.
+
+Pantograph cannot perform things that are inherently constrained by Lean. These
+include:
+
+- If a tactic loses track of metavariables, it will not be caught until the end
+  of the proof search. This is a bug in the tactic itself.
+- Timeouts for executing tactics is not available. Maybe this will change in the
+  future.
+- Interceptions of parsing errors generally cannot be turned into goals (e.g.
+  `def mystery : Nat := :=`) due to Lean's parsing system.
+
+Each Pantograph version is anchored to a Lean version specified in
+`src/lean-toolchain`. Features can be backported to older Lean versions upon
+request.
+
 ## Referencing
 
 [Paper Link](https://arxiv.org/abs/2410.16429)