@goplausible/algorand-mcp 3.0.7

package/dist/resources/knowledge/taxonomy/puya:docs:principles.md

@@ -0,0 +1,196 @@
+# Principles & Background
+## Background
+
+**Smart contracts** on the Algorand blockchain run on the Algorand Virtual Machine ([AVM](https://developer.algorand.org/docs/get-details/dapps/avm/)).
+This is a stack based virtual machine, which executes AVM bytecode as part of an [Application Call transaction](https://developer.algorand.org/docs/get-details/transactions/#application-call-transaction).
+The official mechanism for generating this bytecode is by submitting TEAL (Transaction Execution Approval Language) to 
+an Algorand Node to compile.
+
+**Smart signatures** have the same basis in the AVM and TEAL, but have a different execution model, one not involving 
+Application Call transactions. Our focus will primarily be on smart contracts, since they are strictly more powerful
+in terms of available AVM functions.
+
+TEAL is a [non-structured](https://en.wikipedia.org/wiki/Non-structured_programming) 
+[imperative language](https://en.wikipedia.org/wiki/Procedural_programming#Imperative_programming) 
+(albeit one with support for procedure calls that can isolate stack changes since v8 with `proto`). Writing TEAL is very
+similar to writing assembly code. It goes without saying that this is a particularly common or well-practiced model for 
+programming these days.
+
+As it stands today, developers wanting to write smart contracts specifically for Algorand have the option of writing 
+TEAL directly, or using some other mechanism of generating TEAL such as the officially supported [PyTEAL](https://pyteal.readthedocs.io/en/stable/) 
+or the community supported [tealish](https://tealish.tinyman.org/en/latest/).
+
+PyTEAL follows a [generative programming](https://en.wikipedia.org/wiki/Automatic_programming#Generative_programming) paradigm,
+which is a form of metaprogramming. Naturally, writing programs to generate programs presents an additional hurdle for 
+developers looking to pick up smart contract development. Tooling support for this is also suboptimal, for example, many
+classes of errors resulting from the interaction between the procedural elements of the Python language and the PyTEAL
+expression-building framework go unnoticed until the point of TEAL generation, or worse go completely unnoticed, and even
+when PyTEAL can/does provide an error it can be difficult to understand.
+
+Tealish provides a higher level procedural language, bearing a passing resemblance to Python, than compiles down to TEAL.
+However, it's still lower level than most developers are used to. 
+For example, the expression `1 + 2 + 3`is [not valid in tealish](https://tealish.tinyman.org/en/latest/language.html#math-logic).
+Another difference vs a higher level language such as Python is that [functions can only be declared after the program
+entry point logic](https://tealish.tinyman.org/en/latest/language.html#functions). 
+In essence, tealish abstracts away many difficulties with writing plain TEAL, 
+but it is still essentially more of a transpiler than a compiler. 
+Furthermore, whilst appearing to have syntax inspired by Python, it both adds and removes many fundamental syntax elements,
+presenting an additional learning curve to developers looking to learn blockchain development on Algorand.
+Being a bespoke language also means it has a much smaller ecosystem of tooling built around it compared to languages like
+Python or JavaScript.
+
+To most developers, the Python programming language needs no introduction. First released in 1991, it's popularity has 
+grown steadily over the decades, and as of June 2023 it is consistently ranked as either the most popular langauge, 
+or second most popular following JavaScript:
+
+- [GitHub 2022](https://octoverse.github.com/2022/top-programming-languages)
+- [StackOverflow 2023](https://stackoverflow.blog/2023/06/13/developer-survey-results-are-in/)
+- [Tiobe](https://www.tiobe.com/tiobe-index/)
+- [PYPL](https://pypl.github.io/PYPL.html)
+
+The AlgoKit project is an Algorand Foundation initiative to improve the developer experience on Algorand. Within this
+broad remit, two of the key [principles](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/algokit.md#guiding-principles) 
+are to "meet developers where they are" and "leverage existing ecosystem".
+Building a compiler that allows developers to write smart contracts using an idiomatic subset of a high level language 
+such as Python would make great strides towards both of these goals.
+
+Wyvern was the original internal code name for just such a compiler (now called Puya), one that will transform Python code into valid TEAL 
+smart contracts. In line with the principle of meeting developers where they are, and recognising the popularity of 
+JavaScript and TypeScript, a parallel initiative to build a TypeScript to TEAL compiler is [also underway](https://tealscript.netlify.app).
+
+## Principles
+
+The principles listed here should form the basis of our decision-making, both in the design and implementation.
+
+### Least surprise
+
+Our primary objective is to assist developers in creating accurate smart contracts right from the 
+start. The often immutable nature of these contracts - although not always the case - and the 
+substantial financial value they frequently safeguard, underlines the importance of this goal.
+
+This principle ensures that the code behaves as anticipated by the developer. Specifically, if 
+you're a Python developer writing Python smart contract code, you can expect the code to behave 
+identically to its execution in a standard Python environment.
+
+Furthermore, we believe in promoting explicitness and correctness in contract code and its 
+associated typing. This approach reduces potential errors and enhances the overall integrity of our
+smart contracts. Our commitment is to provide a user-friendly platform that aligns with the 
+developer's intuition and experience, ultimately simplifying their work and minimizing the
+potential for mistakes.
+
+### Inherited from AlgoKit
+
+As a part of the AlgoKit project, the principles outlined [there](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/algokit.md#guiding-principles) 
+also apply - to the extent that this project is just one component of AlgoKit. 
+
+#### "Leverage existing ecosystem"
+
+> AlgoKit functionality gets into the hands of Algorand developers quickly by building on top of the 
+> existing ecosystem wherever possible and aligned to these principles.
+
+In order to leverage as much existing Python tooling as possible, we should strive to maintain the highest level of 
+compatibility with the Python language (and the reference implementation: CPython). 
+
+#### "Meet developers where they are"
+
+> Make Blockchain development mainstream by giving all developers an idiomatic development experience in the operating 
+> system, IDE and language they are comfortable with so they can dive in quickly and have less they need to learn before 
+> being productive.
+
+Python is a very idiomatic language. We should embrace accepted patterns and practices as much as possible,
+such as those listed in [PEP-20](https://peps.python.org/pep-0020/) (aka "The Zen of Python").
+
+#### "Extensible"
+
+> Be extensible for community contribution rather than stifling innovation, bottle-necking all changes through the 
+> Algorand Foundation and preventing the opportunity for other ecosystems being represented (e.g. Go, Rust, etc.). 
+> This helps make developers feel welcome and is part of the developer experience, plus it makes it easier to add 
+> features sustainably
+
+One way to support this principle in the broader AlgoKit context is by building in a mechanism for reusing 
+common code between smart contracts, to allow the community to build their own Python packages.
+
+#### "Sustainable"
+
+> AlgoKit should be built in a flexible fashion with long-term maintenance in mind. Updates to latest patches in 
+> dependencies, Algorand protocol development updates, and community contributions and feedback will all feed in to the 
+> evolution of the software.
+
+Taking this principle further, ensuring the compiler is well-designed (e.g. frontend backend separation, 
+with a well-thought-out IR) will help with maintaining and improving the implementation over time. For example,
+adding in new TEAL language features will be easier, same for implementing new optimisation strategies.
+
+Looking to the future, best practices for smart contract development are rapidly evolving. We shouldn't tie the 
+implementation too tightly to a current standard such as ARC-4 - although in that specific example, we would still
+aim for first class support, but it shouldn't be assumed as the only way to write smart contracts.
+
+
+#### "Modular components"
+
+> Solution components should be modular and loosely coupled to facilitate efficient parallel development by small, 
+> effective teams, reduced architectural complexity and allowing developers to pick and choose the specific tools and 
+> capabilities they want to use based on their needs and what they are comfortable with.
+
+We will focus on the language and compiler design itself.
+
+An example of a very useful feature, that is strongly related but could be implemented separately instead, 
+is the ability to run the users code in a unit-testing context, without compilation+deployment first. 
+This would require implementing in Python some level of simulation of Algorand Nodes / AVM behaviour. 
+
+#### "Secure by default"
+
+> Include defaults, patterns and tooling that help developers write secure code and reduce the likelihood of security 
+> incidents in the Algorand ecosystem. This solution should help Algorand be the most secure Blockchain ecosystem.
+
+Enforcing security (which is multi-faceted) at a compiler level is difficult, and is some cases impossible. 
+The best application of this principle here is to support auditing, which is important and nuanced enough to be 
+listed below as a separate principle.
+
+#### "Cohesive developer tool suite" + "Seamless onramp"
+
+> Cohesive developer tool suite: Using AlgoKit should feel professional and cohesive, like it was designed to work 
+> together, for the developer; not against them. Developers are guided towards delivering end-to-end, high quality 
+> outcomes on MainNet so they and Algorand are more likely to be successful.
+ 
+> Seamless onramp: New developers have a seamless experience to get started and they are guided into a pit of success 
+> with best practices, supported by great training collateral; you should be able to go from nothing to debugging code 
+> in 5 minutes.
+
+These principles relate more to AlgoKit as a whole, so we can respect them by considering the impacts of our decisions
+there more broadly.
+
+### Abstraction without obfuscation
+
+Algorand Python is a high level language, with support for things such as branching logic, operator precedence, etc., 
+and not a set of "macros" for generating TEAL. As such, developers will not be able to directly influence specific TEAL 
+output, if this is desirable a language such as [Tealish](https://tealish.tinyman.org) is more appropriate.
+
+Whilst this will abstract away certain aspects of the underlying TEAL language, there are certain AVM concerns 
+(such as op code budgets) that should not be abstracted away. That said, we should strive to generate code this is
+cost-effective and unsurprising. Python mechanisms such as dynamic (runtime) dispatch, and also many of its builtin
+functions on types such as `str` that are taken for granted, would require large amounts of ops compared to the
+Python code it represents.
+
+### Support auditing
+
+Auditing is a critical part of the security process for deploying smart contracts. We want to support this function,
+and can do so in two ways:
+
+1. By ensuring the same Python code as input generates identical output each time the compiler 
+is run regardless of the system it's running on. This is what might be termed [Output stability](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/articles/output_stability.md).
+Ensuring a consistent output regardless of the system it's run on (assuming the same compiler version), means that
+auditing the lower level (ie TEAL) code is possible. 
+
+2. Although auditing the TEAL code should be possible, being able to easily identify and relate it back to the higher level
+code can make auditing the contract logic simpler and easier. 
+
+### Revolution, not evolution
+
+This is a new and groundbreaking way of developing for Algorand, and not a continuation of the PyTEAL/Beaker approach. 
+By allowing developers to write procedural code, as opposed to constructing an expression tree, 
+we can (among other things) significantly reduce the barrier to entry for developing smart contracts for the Algorand platform.
+
+Since the programming paradigm will be fundamentally different, providing a smooth migration experience from PyTEAL 
+to this new world is not an intended goal, and shouldn't be a factor in our decisions. For example, it is not a goal of
+this project to produce a step-by-step "migrating from PyTEAL" document, as it is not a requirement for users to
+switch to this new paradigm in the short to medium term - support for PyTEAL should continue in parallel.

package/dist/resources/knowledge/taxonomy/puya:examples:auction:README.md

@@ -0,0 +1,3 @@
+Port of Beaker auction contract to TEALScript. Original source: https://github.com/algorand-devrel/beaker-auction/tree/7e1fe62b852c0d819954a931f10cf39d841cbc02 
+
+

package/dist/resources/knowledge/taxonomy/puya:python:testing:README.md

@@ -0,0 +1,66 @@
+<div align="center">
+<a href="https://github.com/algorandfoundation/algorand-python-testing"><img src="https://bafybeiaibjaf6zy6hvef2rrysaacsfsyb3hw4qqtgn657gw7k5tdzqdxzi.ipfs.nftstorage.link/" width=60%></a>
+</div>
+
+<p align="center">
+    <a target="_blank" href="https://algorandfoundation.github.io/algorand-python-testing/"><img src="https://img.shields.io/badge/docs-repository-74dfdc?logo=github&style=flat.svg" /></a>
+    <a target="_blank" href="https://developer.algorand.org/algokit/"><img src="https://img.shields.io/badge/learn-AlgoKit-74dfdc?logo=algorand&mac=flat.svg" /></a>
+    <a target="_blank" href="https://github.com/algorandfoundation/algorand-python-testing"><img src="https://img.shields.io/github/stars/algorandfoundation/algorand-python-testing?color=74dfdc&logo=star&style=flat" /></a>
+    <a target="_blank" href="https://developer.algorand.org/algokit/"><img  src="https://api.visitorbadge.io/api/visitors?path=https%3A%2F%2Fgithub.com%2Falgorandfoundation%2Falgorand-python-testing&countColor=%2374dfdc&style=flat" /></a>
+</p>
+
+---
+
+Algorand Python Testing is a companion package to [Algorand Python](https://github.com/algorandfoundation/puya) that enables efficient unit testing of Algorand Python smart contracts in an offline environment. It emulates key AVM behaviors without requiring a network connection, offering fast and reliable testing capabilities with a familiar Pythonic interface.
+
+[Documentation](https://algorandfoundation.github.io/algorand-python-testing/) | [Algorand Python Documentation](https://algorandfoundation.github.io/puya/)
+
+## Quick start
+
+The easiest way to use Algorand Python Testing is to instantiate a template with AlgoKit via `algokit init -t python`. This will give you a full development environment with testing capabilities built-in.
+
+Alternatively, if you want to start from scratch:
+
+1. Ensure you have Python 3.12+
+2. Install [AlgoKit CLI](https://github.com/algorandfoundation/algokit-cli?tab=readme-ov-file#install)
+3. Install Algorand Python Testing into your project:
+    ```bash
+    pip install algorand-python-testing
+    ```
+4. Create a test file (e.g., `test_contract.py`):
+
+    ```python
+    from algopy_testing import algopy_testing_context
+    from your_contract import YourContract
+    
+    def test_your_contract():
+        with algopy_testing_context() as context:
+            # Arrange
+            contract = YourContract()
+            expected_result = ... # Your expected result here
+    
+            # Act
+            result = contract.your_method(context.any.uint64())  # Your test code here
+    
+            # Assert
+            assert result == expected_result
+    ```
+
+5. Run your tests using your preferred Python testing framework (e.g., pytest, unittest)
+
+For more detailed information, check out the [full documentation](https://algorandfoundation.github.io/algorand-python-testing/).
+
+## Features
+
+-   Offline testing environment simulating core AVM functionality
+-   Compatible with popular Python testing frameworks
+-   Supports testing of ARC4 contracts, smart signatures, and more
+-   Provides tools for mocking blockchain state and transactions
+
+## Examples
+
+For detailed examples showcasing various testing scenarios, refer to the [examples section](https://algorandfoundation.github.io/algorand-python-testing/examples.html) in the documentation.
+
+## Contributing
+
+We welcome contributions to this project! Please read our [contributing guide](CONTRIBUTING.md) to get started.

package/dist/resources/knowledge/taxonomy/puya:python:testing:docs:algopy.md

@@ -0,0 +1,9 @@
+# Algorand Python
+
+Algorand Python is a partial implementation of the Python programming language that runs on the AVM. It includes a statically typed framework for development of Algorand smart contracts and logic signatures, with Pythonic interfaces to underlying AVM functionality that works with standard Python tooling.
+
+Algorand Python is compiled for execution on the AVM by PuyaPy, an optimising compiler that ensures the resulting AVM bytecode execution semantics that match the given Python code. PuyaPy produces output that is directly compatible with [AlgoKit typed clients](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/generate.md#1-typed-clients) to make deployment and calling easy.
+
+## Quick start
+
+To get started refer to the [official documentation](https://algorandfoundation.github.io/puya).

package/dist/resources/knowledge/taxonomy/puya:python:testing:docs:api.md

@@ -0,0 +1,41 @@
+# API Reference
+
+An overview of the `algorand-python-testing`'s `algopy_testing` module - covering the main classes and functions.
+
+```{hint}
+Spotted a typo in documentation? This project is open source, please submit an issue or a PR on [GitHub](https://github.com/algorand/algorand-python-testing).
+```
+
+```{warning}
+Note, assume `_algopy_testing` to refer to `algopy_testing` namespace in the auto-generated class documentation above. To be patched in near future.
+```
+
+## Contexts
+
+```{autodoc2-summary}
+algopy_testing.AlgopyTestContext
+algopy_testing.LedgerContext
+algopy_testing.TransactionContext
+```
+
+## Value Generators
+
+```{autodoc2-summary}
+algopy_testing.AVMValueGenerator
+algopy_testing.ARC4ValueGenerator
+algopy_testing.TxnValueGenerator
+```
+
+## Inner transaction loaders
+
+```{autodoc2-summary}
+algopy_testing.ITxnGroupLoader
+algopy_testing.ITxnLoader
+```
+
+## Utils
+
+```{autodoc2-summary}
+algopy_testing.algopy_testing_context
+algopy_testing.arc4_prefix
+```

package/dist/resources/knowledge/taxonomy/puya:python:testing:docs:coverage.md

@@ -0,0 +1,159 @@
+# Coverage
+
+See which `algorand-python` stubs are implemented by the `algorand-python-testing` library. See the [Concepts](testing-guide/concepts.md#types-of-algopy-stub-implementations) section for more details on the implementation categories. Refer to the [`algorand-python` stubs API](api.md) for the full list of the stubs for which the `algorand-python-testing` library provides implementations referenced in the table below.
+
+| Name                                        | Implementation type |
+| ------------------------------------------- | ------------------- |
+| algopy.Account                              | Emulated            |
+| algopy.Application                          | Emulated            |
+| algopy.Asset                                | Emulated            |
+| algopy.BigUInt                              | Native              |
+| algopy.Box                                  | Emulated            |
+| algopy.BoxMap                               | Emulated            |
+| algopy.BoxRef                               | Emulated            |
+| algopy.Bytes                                | Native              |
+| algopy.BytesBacked                          | Native              |
+| algopy.CompiledContract                     | Mockable            |
+| algopy.CompiledLogicSig                     | Mockable            |
+| algopy.Contract                             | Emulated            |
+| algopy.Global                               | Emulated            |
+| algopy.GlobalState                          | Emulated            |
+| algopy.LocalState                           | Emulated            |
+| algopy.LogicSig                             | Emulated            |
+| algopy.OnCompleteAction                     | Native              |
+| algopy.OpUpFeeSource                        | Native              |
+| algopy.StateTotals                          | Emulated            |
+| algopy.String                               | Native              |
+| algopy.TemplateVar                          | Emulated            |
+| algopy.TransactionType                      | Native              |
+| algopy.Txn                                  | Emulated            |
+| algopy.UInt64                               | Native              |
+| algopy.compile_contract                     | Mockable            |
+| algopy.compile_logicsig                     | Mockable            |
+| algopy.ensure_budget                        | Emulated            |
+| algopy.log                                  | Emulated            |
+| algopy.logicsig                             | Emulated            |
+| algopy.subroutine                           | Native              |
+| algopy.uenumerate                           | Native              |
+| algopy.urange                               | Native              |
+| algopy.arc4.ARC4Client                      | Emulated            |
+| algopy.arc4.ARC4Contract                    | Emulated            |
+| algopy.arc4.Address                         | Native              |
+| algopy.arc4.BigUFixedNxM                    | Native              |
+| algopy.arc4.BigUIntN                        | Native              |
+| algopy.arc4.Bool                            | Native              |
+| algopy.arc4.Byte                            | Native              |
+| algopy.arc4.DynamicArray                    | Native              |
+| algopy.arc4.DynamicBytes                    | Native              |
+| algopy.arc4.StaticArray                     | Native              |
+| algopy.arc4.String                          | Native              |
+| algopy.arc4.Struct                          | Native              |
+| algopy.arc4.Tuple                           | Native              |
+| algopy.arc4.UFixedNxM                       | Native              |
+| algopy.arc4.UInt128                         | Native              |
+| algopy.arc4.UInt16                          | Native              |
+| algopy.arc4.UInt256                         | Native              |
+| algopy.arc4.UInt32                          | Native              |
+| algopy.arc4.UInt512                         | Native              |
+| algopy.arc4.UInt64                          | Native              |
+| algopy.arc4.UInt8                           | Native              |
+| algopy.arc4.UIntN                           | Native              |
+| algopy.arc4.abimethod                       | Emulated            |
+| algopy.arc4.arc4_signature                  | Native              |
+| algopy.arc4.baremethod                      | Emulated            |
+| algopy.arc4.emit                            | Emulated            |
+| algopy.arc4.abi_call                        | Mockable            |
+| algopy.arc4.arc4_create                     | Mockable            |
+| algopy.arc4.arc4_update                     | Mockable            |
+| algopy.gtxn.ApplicationCallTransaction      | Emulated            |
+| algopy.gtxn.AssetConfigTransaction          | Emulated            |
+| algopy.gtxn.AssetFreezeTransaction          | Emulated            |
+| algopy.gtxn.AssetTransferTransaction        | Emulated            |
+| algopy.gtxn.KeyRegistrationTransaction      | Emulated            |
+| algopy.gtxn.PaymentTransaction              | Emulated            |
+| algopy.gtxn.Transaction                     | Emulated            |
+| algopy.gtxn.TransactionBase                 | Emulated            |
+| algopy.itxn.ApplicationCall                 | Emulated            |
+| algopy.itxn.ApplicationCallInnerTransaction | Emulated            |
+| algopy.itxn.AssetConfig                     | Emulated            |
+| algopy.itxn.AssetConfigInnerTransaction     | Emulated            |
+| algopy.itxn.AssetFreeze                     | Emulated            |
+| algopy.itxn.AssetFreezeInnerTransaction     | Emulated            |
+| algopy.itxn.AssetTransfer                   | Emulated            |
+| algopy.itxn.AssetTransferInnerTransaction   | Emulated            |
+| algopy.itxn.InnerTransaction                | Emulated            |
+| algopy.itxn.InnerTransactionResult          | Emulated            |
+| algopy.itxn.KeyRegistration                 | Emulated            |
+| algopy.itxn.KeyRegistrationInnerTransaction | Emulated            |
+| algopy.itxn.Payment                         | Emulated            |
+| algopy.itxn.PaymentInnerTransaction         | Emulated            |
+| algopy.itxn.submit_txns                     | Emulated            |
+| algopy.op.Base64                            | Native              |
+| algopy.op.EC                                | Native              |
+| algopy.op.ECDSA                             | Native              |
+| algopy.op.JsonRef                           | Native              |
+| algopy.op.addw                              | Native              |
+| algopy.op.arg                               | Emulated            |
+| algopy.op.base64_decode                     | Native              |
+| algopy.op.bitlen                            | Native              |
+| algopy.op.bsqrt                             | Native              |
+| algopy.op.btoi                              | Native              |
+| algopy.op.bzero                             | Native              |
+| algopy.op.concat                            | Native              |
+| algopy.op.divmodw                           | Native              |
+| algopy.op.divw                              | Native              |
+| algopy.op.ecdsa_pk_decompress               | Native              |
+| algopy.op.ecdsa_pk_recover                  | Native              |
+| algopy.op.ecdsa_verify                      | Native              |
+| algopy.op.ed25519verify                     | Native              |
+| algopy.op.ed25519verify_bare                | Native              |
+| algopy.op.err                               | Native              |
+| algopy.op.exit                              | Native              |
+| algopy.op.exp                               | Native              |
+| algopy.op.expw                              | Native              |
+| algopy.op.extract                           | Native              |
+| algopy.op.extract_uint16                    | Native              |
+| algopy.op.extract_uint32                    | Native              |
+| algopy.op.extract_uint64                    | Native              |
+| algopy.op.getbit                            | Native              |
+| algopy.op.getbyte                           | Native              |
+| algopy.op.itob                              | Native              |
+| algopy.op.keccak256                         | Native              |
+| algopy.op.mulw                              | Native              |
+| algopy.op.replace                           | Native              |
+| algopy.op.select_bytes                      | Native              |
+| algopy.op.select_uint64                     | Native              |
+| algopy.op.setbit_bytes                      | Native              |
+| algopy.op.setbit_uint64                     | Native              |
+| algopy.op.setbyte                           | Native              |
+| algopy.op.sha256                            | Native              |
+| algopy.op.sha3_256                          | Native              |
+| algopy.op.sha512_256                        | Native              |
+| algopy.op.shl                               | Native              |
+| algopy.op.shr                               | Native              |
+| algopy.op.sqrt                              | Native              |
+| algopy.op.substring                         | Native              |
+| algopy.op.AppGlobal                         | Emulated            |
+| algopy.op.AppLocal                          | Emulated            |
+| algopy.op.AppParamsGet                      | Emulated            |
+| algopy.op.AssetHoldingGet                   | Emulated            |
+| algopy.op.AssetParamsGet                    | Emulated            |
+| algopy.op.Block                             | Emulated            |
+| algopy.op.Box                               | Emulated            |
+| algopy.op.GITxn                             | Emulated            |
+| algopy.op.GTxn                              | Emulated            |
+| algopy.op.Global                            | Emulated            |
+| algopy.op.ITxn                              | Emulated            |
+| algopy.op.ITxnCreate                        | Emulated            |
+| algopy.op.Scratch                           | Emulated            |
+| algopy.op.Txn                               | Emulated            |
+| algopy.op.app_opted_in                      | Emulated            |
+| algopy.op.balance                           | Emulated            |
+| algopy.op.gaid                              | Emulated            |
+| algopy.op.gload_bytes                       | Emulated            |
+| algopy.op.gload_uint64                      | Emulated            |
+| algopy.op.min_balance                       | Emulated            |
+| algopy.op.AcctParamsGet                     | Emulated            |
+| algopy.op.EllipticCurve                     | Mockable            |
+| algopy.op.VrfVerify                         | Mockable            |
+| algopy.op.vrf_verify                        | Mockable            |

package/dist/resources/knowledge/taxonomy/puya:python:testing:docs:examples.md

@@ -0,0 +1,13 @@
+# Examples
+
+Below is a showcase of various examples of unit testing real and sample Algorand Python smart contracts using `algorand-python-testing`.
+
+| Contract Name       | Test File                                                                                                                                 | Key Features Demonstrated                                                                                                                                                                                        | Test versions of Algopy Abstractions used                                                           |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| Auction             | [test_contract.py](https://github.com/algorandfoundation/algorand-python-testing/blob/main/examples/auction/test_contract.py)             | - Use of algopy_testing_context<br>- Mocking of global state and transaction fields<br>- Testing of ARC4 contract methods<br>- Emulation of asset creation and transfers<br>- Verification of inner transactions | - **ARC4Contract**<br>- **Global**<br>- **Txn**<br>- **Asset**<br>- **Account**<br>- **LocalState** |
+| Proof of Attendance | [test_contract.py](https://github.com/algorandfoundation/algorand-python-testing/blob/main/examples/proof_of_attendance/test_contract.py) | - Creation and management of dummy assets<br>- Testing of box storage operations<br>- Verification of inner transactions for asset transfers<br>- Use of any\_\* methods for generating test data                | - **ARC4Contract**<br>- **Box**<br>- **BoxMap**<br>- **Asset**<br>- **Account**<br>- **op**         |
+| Simple Voting       | [test_contract.py](https://github.com/algorandfoundation/algorand-python-testing/blob/main/examples/simple_voting/test_contract.py)       | - Testing of global and local state operations<br>- Verification of transaction group operations<br>- Mocking of payment transactions                                                                            | - **Contract**<br>- **GlobalState**<br>- **LocalState**<br>- **Txn**<br>- **op.GTxn**               |
+| ZK Whitelist        | [test_contract.py](https://github.com/algorandfoundation/algorand-python-testing/blob/main/examples/zk_whitelist/test_contract.py)        | - Testing of zero-knowledge proof verification<br>- Mocking of external application calls<br>- Use of ARC4 types and methods                                                                                     | - **ARC4Contract**<br>- **arc4 types**<br>- **LocalState**<br>- **Global**<br>- **Txn**             |
+| HTLC LogicSig       | [test_signature.py](https://github.com/algorandfoundation/algorand-python-testing/blob/main/examples/htlc_logicsig/test_signature.py)     | - Testing of LogicSig contracts<br>- Verification of time-based conditions<br>- Mocking of transaction parameters                                                                                                | - **logicsig**<br>- **Account**<br>- **Txn**<br>- **Global**<br>- **op**                            |
+| Marketplace         | [test_contract.py](https://github.com/algorandfoundation/algorand-python-testing/blob/main/examples/marketplace/test_contract.py)         | - Testing of complex marketplace operations<br>- Use of BoxMap for listings<br>- Testing of asset transfers and payments                                                                                         | - **ARC4Contract**<br>- **BoxMap**<br>- **Asset**<br>- **arc4 types**<br>- **Global**<br>- **Txn**  |
+| Scratch Storage     | [test_contract.py](https://github.com/algorandfoundation/algorand-python-testing/blob/main/examples/scratch_storage/test_contract.py)     | - Testing of scratch space usage<br>- Verification of scratch slot values                                                                                                                                        | - **ARC4Contract**<br>- **Contract**<br>- **op**                                                    |

package/dist/resources/knowledge/taxonomy/puya:python:testing:docs:faq.md

@@ -0,0 +1,61 @@
+# FAQ
+
+## What is a Test Context?
+
+A Test Context is a context manager that provides a simulated Algorand environment for testing Python smart contracts. It allows developers to create and manipulate a virtual Algorand ecosystem for testing purposes. For more details, see the [Test Context section](testing-guide/concepts.md#test-context) in our documentation.
+
+## What is the Algorand Virtual Machine (AVM)?
+
+The Algorand Virtual Machine (AVM) is the runtime environment for Algorand smart contracts. It executes the compiled code of smart contracts on the Algorand blockchain. To learn more about the AVM, visit the [official Algorand documentation](https://developer.algorand.org/docs/get-details/dapps/avm/).
+
+## What are Operational Codes in Algorand?
+
+Operational Codes, or opcodes, are AVM instructions that are executed directly by the AVM. In the context of Algorand Python testing, these opcodes are provided by `algopy` stubs and are either emulated, implemented, or mocked by `algorand-python-testing`. For a comprehensive list of opcodes, refer to the [Algorand Developer Documentation](https://developer.algorand.org/docs/get-details/dapps/avm/teal/opcodes/?from_query=OPcodes#template-modal-overlay).
+
+## What are Value Generators?
+
+Value Generators are helper methods that generate randomized values for testing when the specific value of the tested type is not important. In the context of Algorand Python testing, these are represented by property on the context manager, accessed via `any.*` (or `any.arc4.*`, `any.txn.*`. in the case of ARC 4 types). To understand how to use Value Generators effectively, check out our [Value Generators section](testing-guide/concepts.md#value-generators) in the documentation.
+
+## What are the limitations of the Algorand Python Testing framework?
+
+The Algorand Python Testing framework emulates the Algorand Virtual Machine (AVM) for unit testing Algorand Python smart contracts without interacting with the real Algorand Network. However, it has some limitations due to its scope and purpose:
+
+1. Simplified balance tracking and transaction validation
+2. No consensus mechanism or AVM network operations simulation
+3. Absence of a strict opcode budget system
+4. Certain cryptographic operations are mocked or simplified
+5. No state proof generation or verification
+
+For scenarios where these limitations are crucial, it's recommended to pair this framework with integration testing. If you have a solid reason to justify introducing new emulated behaviour, please open an issue or contribute to the project on [Github](https://github.com/algorandfoundation/algorand-python-testing).
+
+## How does balance tracking work in the testing framework?
+
+The framework uses simplified balance tracking and transaction validation. For scenarios where precise balance or fee verification is important, it's recommended to complement unit tests with integration testing.
+
+## Does the framework simulate the entire AVM network?
+
+No, the framework does not simulate the entire AVM network or consensus mechanism. It focuses on emulating the parts of the AVM relevant to unit testing smart contracts.
+
+## How does the framework handle opcode budgets?
+
+The framework does not implement a strict opcode budget system. For scenarios where validating opcode budget is crucial, it's recommended to use integration testing alongside this framework.
+
+## Are all cryptographic operations fully implemented?
+
+Some cryptographic operations are mocked or simplified in the framework. For a detailed list of which operations are mocked, refer to the _mockable_ types under the [coverage](./coverage.md) section.
+
+## Can I use this framework for security-critical validations?
+
+While this framework is useful for unit testing and local development, it should not be the only tool used for security-critical validations or performance benchmarking. It's designed to approximate AVM behavior for common scenarios. Always complement your testing with additional integration testing options available in `algokit`, where you can test against real localnet or testnet environments.
+
+## Is there an example of how to use this framework alongside integration tests?
+
+Yes, the `algokit-python-template`, accessible via `algokit init`, provides a working example of how to structure `algorand-python-testing` along with regular integration tests against localnet.
+
+```{hint}
+An `algokit-python-template` accessible via `algokit init -t python`, provides a comprehensive and customizable working example of how to structure `algorand-python-testing` along with regular integration tests against localnet.
+```
+
+## Is it compatible with `pytest`?
+
+Yes, it is compatible with `pytest` and _any_ other python testing framework as its agnostic of the testing framework as long as its python. If you spot incompatibility with a certain tool, please open an issue or contribute to the project on [Github](https://github.com/algorandfoundation/algorand-python-testing).